agentvibes 5.12.0 → 5.13.1

package/mcp-server/server.py

@@ -46,6 +46,7 @@ import os
 import platform
 import re as _re
 import subprocess
+import sys
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Optional
@@ -61,6 +62,53 @@ import mcp.server.stdio
 DEFAULT_SCRIPT_TIMEOUT = 30.0
 
 
+# ── Provider Catalog (SSOT Layer 2) — platform allowlists + display names ────
+#
+# server.py DERIVES its per-platform provider allowlists and provider display
+# names from the shipped provider-catalog.json (generated from
+# src/services/provider-catalog.js). The literals below are an EMBEDDED FALLBACK
+# used ONLY when that JSON is missing or unreadable (installed-tree skew) —
+# degraded, never dead: the MCP server MUST start without the file.
+#
+# Bidirectional parity (embedded fallback ≡ catalog, per platform, BOTH
+# directions) is asserted by test/unit/provider-catalog-conformance.test.js so
+# the fallback can never silently drift from the catalog (design §8 — a
+# one-directional check is the exact gap that let elevenlabs-on-Windows through
+# the old positive-only test).
+#
+# The non-Windows fallback mirrors the catalog's DARWIN set (the superset that
+# also covers Linux: darwin adds macOS `say`, which a Linux box simply won't
+# have installed — availability is enforced by the dispatchers downstream, not
+# here). Windows uses the catalog WINDOWS set. elevenlabs is deliberately ABSENT
+# from Windows: there is NO play-tts-elevenlabs.ps1 runtime (AVI-S9.1 /
+# provider-catalog.js: elevenlabs.runtime.windows === null).
+_FALLBACK_PROVIDERS_WINDOWS = ["windows-piper", "windows-sapi", "soprano", "kokoro"]
+_FALLBACK_PROVIDERS_NON_WINDOWS = ["piper", "macos", "soprano", "kokoro", "elevenlabs"]
+
+# termux-ssh is a TRANSPORT (relays TTS over SSH to a phone), NOT a synthesis
+# provider: it has no catalog record and no play-tts-termux-ssh runtime. It is
+# accepted on non-Windows as a documented non-catalog transport token, and is
+# EXCLUDED BY NAME from the catalog parity assertion (AC6) so it can neither be
+# silently dropped nor silently drift INTO the catalog.
+_TRANSPORT_TOKENS = ["termux-ssh"]
+
+# Embedded fallback display names — byte-equal to catalog.json `displayNames`
+# (group-8 parity). termux-ssh is NOT here (it has no catalog record); its
+# display name is added separately as a transport token.
+_FALLBACK_DISPLAY_NAMES = {
+    "soprano": "Soprano TTS",
+    "piper": "Piper TTS",
+    "kokoro": "Kokoro TTS",
+    "elevenlabs": "ElevenLabs",
+    "macos": "macOS Say",
+    "windows-sapi": "Windows SAPI",
+    "windows-piper": "Piper TTS",
+}
+_TRANSPORT_DISPLAY_NAMES = {
+    "termux-ssh": "Termux SSH",
+}
+
+
 @dataclass
 class ScriptResult:
     """Structured result of running a hook script.
@@ -127,6 +175,91 @@ class AgentVibesServer:
         # the same file at the same time is not covered; see story 8.2 notes).
         self._override_lock = asyncio.Lock()
 
+        # provider-catalog.json is read lazily once and cached (design: no
+        # blocking I/O per call; load at first use, not per set_provider).
+        self._provider_catalog = None
+        self._provider_catalog_loaded = False
+
+    def _load_provider_catalog(self) -> Optional[dict]:
+        """Load the shipped provider-catalog.json ONCE (cached).
+
+        Generated from src/services/provider-catalog.js into
+        .claude/hooks/provider-catalog.json and shipped beside the hooks, it is
+        the SSOT for per-platform provider allowlists and display names. Returns
+        the parsed dict, or None on ANY failure (missing / unreadable /
+        malformed) so the MCP server always starts — callers then fall back to
+        the embedded literals that conformance asserts are equivalent.
+        """
+        if self._provider_catalog_loaded:
+            return self._provider_catalog
+        self._provider_catalog_loaded = True
+        catalog = None
+        try:
+            # catalog.json lives under hooks/ on EVERY platform (program data,
+            # not a per-platform hook script — the generator only writes it there).
+            path = self.claude_dir / "hooks" / "provider-catalog.json"
+            if path.exists() and not path.is_symlink():
+                parsed = json.loads(path.read_text(encoding="utf-8"))
+                if isinstance(parsed, dict):
+                    catalog = parsed
+        except (OSError, ValueError):
+            catalog = None
+        if catalog is None:
+            # Degraded, never dead. Warn on stderr ONLY (stdout is the MCP
+            # JSON-RPC stream); one terse line, since a missing file is the
+            # common installed-tree-skew case.
+            print(
+                "agentvibes: provider-catalog.json unavailable; using embedded provider fallback",
+                file=sys.stderr,
+            )
+        self._provider_catalog = catalog
+        return catalog
+
+    def _valid_providers(self) -> list:
+        """Per-platform provider allowlist, DERIVED from provider-catalog.json.
+
+        Windows → catalog `platforms.windows`; non-Windows → catalog
+        `platforms.darwin` (the superset covering both Linux and macOS). Falls
+        back to the embedded literals when the catalog is unavailable. Transport
+        tokens (termux-ssh) are appended on non-Windows only.
+        """
+        catalog = self._load_provider_catalog()
+        base = None
+        if catalog:
+            platforms = catalog.get("platforms")
+            if isinstance(platforms, dict):
+                key = "windows" if self.is_windows else "darwin"
+                derived = platforms.get(key)
+                if isinstance(derived, list) and derived:
+                    base = list(derived)
+        if base is None:
+            base = list(
+                _FALLBACK_PROVIDERS_WINDOWS if self.is_windows else _FALLBACK_PROVIDERS_NON_WINDOWS
+            )
+        if not self.is_windows:
+            for token in _TRANSPORT_TOKENS:
+                if token not in base:
+                    base.append(token)
+        return base
+
+    def _provider_display_names(self) -> dict:
+        """Provider display names, DERIVED from provider-catalog.json.
+
+        Falls back to the embedded dict when the catalog is unavailable. Non-
+        catalog transport tokens (termux-ssh) are always merged in.
+        """
+        catalog = self._load_provider_catalog()
+        names = None
+        if catalog:
+            derived = catalog.get("displayNames")
+            if isinstance(derived, dict) and derived:
+                names = dict(derived)
+        if names is None:
+            names = dict(_FALLBACK_DISPLAY_NAMES)
+        for token, label in _TRANSPORT_DISPLAY_NAMES.items():
+            names.setdefault(token, label)
+        return names
+
     def _find_claude_dir(self) -> Path:
         """Find the .claude directory relative to this script"""
         # Get the AgentVibes root directory (parent of mcp-server)
@@ -728,33 +861,31 @@ class AgentVibesServer:
 
     async def set_provider(self, provider: str) -> str:
         """
-        Switch TTS provider between Piper, macOS, and Termux SSH.
+        Switch TTS provider between the supported synthesis engines.
 
         Args:
-            provider: Provider name ("piper", "macos", or "termux-ssh")
+            provider: Provider name. Non-Windows: "piper", "macos", "termux-ssh",
+                "soprano", "kokoro", "elevenlabs". Windows: "windows-piper",
+                "windows-sapi", "soprano", "kokoro".
 
         Returns:
             Success or error message
         """
         provider = provider.lower()
-        if self.is_windows:
-            valid_providers = ["windows-piper", "windows-sapi", "soprano"]
-        else:
-            valid_providers = ["piper", "macos", "termux-ssh", "soprano"]
+        # Platform allowlist + display names DERIVE from provider-catalog.json
+        # (SSOT), with embedded fallbacks (module constants above). kokoro is
+        # cross-platform; elevenlabs is Unix-only (NO play-tts-elevenlabs.ps1, so
+        # it is absent from the Windows set — switching to it on Windows would be
+        # silently unplayable). See AVI-S9.1 / AVI-S9.5 and provider-catalog.js
+        # (elevenlabs.runtime.windows === null).
+        valid_providers = self._valid_providers()
         if provider not in valid_providers:
             return f"❌ Invalid provider: {provider}. Choose from: {', '.join(valid_providers)}"
 
         result = await self._run_script("provider-manager.sh", ["switch", provider])
         if result.ok:
-            # Automatically speak confirmation in the new provider's voice
-            provider_names = {
-                "macos": "macOS",
-                "termux-ssh": "Termux SSH",
-                "piper": "Piper",
-                "windows-piper": "Windows Piper",
-                "windows-sapi": "Windows SAPI",
-                "soprano": "Soprano",
-            }
+            # Automatically speak confirmation in the new provider's voice.
+            provider_names = self._provider_display_names()
             provider_name = provider_names.get(provider, provider.title())
             confirmation_text = f"Successfully switched to {provider_name} provider"
 
@@ -775,24 +906,6 @@ class AgentVibesServer:
 
         return f"❌ Failed to switch provider: {result.error_detail}"
 
-    async def set_learn_mode(self, enabled: bool) -> str:
-        """
-        Enable or disable language learning mode.
-
-        When enabled, TTS speaks in both your main language and target language.
-
-        Args:
-            enabled: True to enable, False to disable
-
-        Returns:
-            Success or error message
-        """
-        action = "enable" if enabled else "disable"
-        result = await self._run_script("learn-manager.sh", [action])
-        if result.ok:
-            return result.stdout if "✓" in result.stdout else f"✓ {result.stdout}"
-        return f"❌ Failed to set learn mode: {result.error_detail}"
-
     async def set_speed(self, speed: str, target: bool = False) -> str:
         """
         Set speech speed for main or target voice.
@@ -1591,20 +1704,6 @@ Examples:
                 "required": ["provider"],
             },
         ),
-        Tool(
-            name="set_learn_mode",
-            description="Enable or disable language learning mode. When ON, TTS speaks in both your main language and target language for bilingual learning.",
-            inputSchema={
-                "type": "object",
-                "properties": {
-                    "enabled": {
-                        "type": "boolean",
-                        "description": "True to enable learning mode, False to disable"
-                    }
-                },
-                "required": ["enabled"],
-            },
-        ),
         Tool(
             name="set_speed",
             description="Set speech speed for main or target voice. Works with both Piper and macOS providers. Use this to make voices faster or slower.",
@@ -1900,8 +1999,6 @@ async def call_tool(name: str, arguments: dict) -> list[TextContent] | CallToolR
             result = await agent_vibes.replay_audio(n)
         elif name == "set_provider":
             result = await agent_vibes.set_provider(arguments["provider"])
-        elif name == "set_learn_mode":
-            result = await agent_vibes.set_learn_mode(arguments["enabled"])
         elif name == "set_speed":
             target = arguments.get("target", False)
             result = await agent_vibes.set_speed(arguments["speed"], target)

package/mcp-server/test_mcp_correctness.py

@@ -122,13 +122,12 @@ def test_set_personality_fails_on_nonzero_exit_despite_matching_marker_text():
     "method_name,call_args,plain_stdout",
     [
         ("set_language", ("spanish",), "Language set to: spanish"),
-        ("set_learn_mode", (True,), "Learn mode enabled"),
         ("set_verbosity", ("high",), "Verbosity set to: high (project-local)"),
         ("replay_audio", (1,), "Replaying audio #1: tts-foo.wav"),
     ],
 )
 def test_windows_style_plain_text_success_is_not_treated_as_failure(method_name, call_args, plain_stdout):
-    """set_language / set_learn_mode / set_verbosity / replay_audio must all
+    """set_language / set_verbosity / replay_audio must all
     report success from returncode==0 alone, even when stdout carries none of
     the emoji markers the old code sniffed for (✓ / ✅ / 🔊)."""
     server = AgentVibesServer()
@@ -482,5 +481,24 @@ def test_tool_descriptions_state_20_percent_default_not_30():
     assert "0.30" not in volume_desc
 
 
+def test_valid_providers_derives_from_catalog_and_excludes_elevenlabs_on_windows():
+    """AVI-S9.5: _valid_providers() derives the per-platform allowlist from
+    provider-catalog.json (or the embedded fallback ≡ catalog). ElevenLabs has
+    no Windows runtime (no play-tts-elevenlabs.ps1), so it must be ABSENT from
+    the Windows allowlist and PRESENT on non-Windows — the exact bug class the
+    Provider Catalog closes."""
+    server = AgentVibesServer()
+
+    server.is_windows = True
+    win = server._valid_providers()
+    assert "elevenlabs" not in win, f"elevenlabs must not be a Windows provider: {win}"
+    assert "kokoro" in win and "soprano" in win
+
+    server.is_windows = False
+    non_win = server._valid_providers()
+    assert "elevenlabs" in non_win, f"elevenlabs must be a non-Windows provider: {non_win}"
+    assert "kokoro" in non_win and "soprano" in non_win
+
+
 if __name__ == "__main__":
     sys.exit(pytest.main([__file__, "-v"]))

package/mcp-server/test_windows_script_parity.py

@@ -42,7 +42,6 @@ HOOKS_LINUX = PROJECT_ROOT / ".claude" / "hooks"
 # The auto-conversion (server.py:902-903) converts .sh -> .ps1
 MCP_HARDCODED_SCRIPTS = [
     "provider-manager",
-    "learn-manager",
     "speed-manager",
     "download-extra-voices",
     "verbosity-manager",
@@ -159,7 +158,6 @@ def test_run_script_error_for_missing():
 MCP_TOOL_SCRIPT_MAP = {
     "set_speed": "speed-manager",
     "get_speed": "speed-manager",
-    "set_learn_mode": "learn-manager",
     "set_verbosity": "verbosity-manager",
     "get_verbosity": "verbosity-manager",
     "mute": "verbosity-manager",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "agentvibes",
-  "version": "5.12.0",
+  "version": "5.13.1",
   "description": "Now your AI Agents can finally talk back! Professional TTS voice for Claude Code, Claude Desktop (via MCP), and Clawdbot with multi-provider support.",
   "homepage": "https://agentvibes.org",
   "keywords": [
@@ -96,7 +96,7 @@
     "commander": "^10.0.0",
     "figlet": "^1.6.0",
     "inquirer": "^12.0.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^4.3.0",
     "ora": "^6.0.0"
   },
   "engines": {

package/src/cli/list-voices.js

@@ -1,114 +1,218 @@
-#!/usr/bin/env node
-/**
- * Voice List Display - Beautiful multi-column voice listing
- * Called by voice-manager.sh to display voices with boxen formatting
- */
-
-import { formatVoicesList } from '../utils/list-formatter.js';
-import fs from 'fs';
-import path from 'path';
-import { execFileSync } from 'child_process';
-import os from 'os';
-
-/**
- * Get Piper voices from voice directory
- */
-function getPiperVoices(voiceDir, currentVoice) {
-  const voices = [];
-
-  if (!fs.existsSync(voiceDir)) {
-    return voices;
-  }
-
-  const files = fs.readdirSync(voiceDir);
-  for (const file of files) {
-    if (file.endsWith('.onnx')) {
-      const voiceName = path.basename(file, '.onnx');
-      voices.push({
-        name: voiceName,
-        lang: extractLanguage(voiceName),
-        current: voiceName === currentVoice
-      });
-    }
-  }
-
-  return voices.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-/**
- * Get macOS voices using say -v ?
- */
-function getMacOSVoices(currentVoice) {
-  const voices = [];
-
-  if (os.platform() !== 'darwin') {
-    return voices;
-  }
-
-  try {
-    const output = execFileSync('say', ['-v', '?'], { encoding: 'utf8' }); // NOSONAR - Safe: checking macOS say voices from system PATH
-    const lines = output.split('\n');
-
-    for (const line of lines) {
-      if (!line.trim()) continue;
-
-      const parts = line.trim().split(/\s+/);
-      if (parts.length >= 2) {
-        const voiceName = parts[0];
-        const lang = parts[1];
-
-        voices.push({
-          name: voiceName,
-          lang,
-          current: voiceName === currentVoice
-        });
-      }
-    }
-  } catch (error) {
-    // say command failed
-  }
-
-  return voices;
-}
-
-/**
- * Extract language code from voice name
- */
-function extractLanguage(voiceName) {
-  const match = voiceName.match(/^([a-z]{2}_[A-Z]{2})/);
-  return match ? match[1] : '';
-}
-
-/**
- * Main function
- */
-function main() {
-  const args = process.argv.slice(2);
-
-  // Parse arguments
-  const provider = args[0] || 'piper';
-  const currentVoice = args[1] || '';
-  const voiceDir = args[2] || '';
-
-  let voices = [];
-  let providerName = 'Piper TTS';
-
-  if (provider === 'piper') {
-    voices = getPiperVoices(voiceDir, currentVoice);
-    providerName = 'Piper TTS';
-  } else if (provider === 'macos') {
-    voices = getMacOSVoices(currentVoice);
-    providerName = 'macOS TTS';
-  }
-
-  // Display with boxen
-  const output = formatVoicesList(voices, {
-    provider: providerName,
-    columns: 2,
-    showUsage: true
-  });
-
-  console.log(output);
-}
-
-main();
+#!/usr/bin/env node
+/**
+ * Voice List Display - Beautiful multi-column voice listing
+ * Called by voice-manager.sh to display voices with boxen formatting
+ */
+
+import { formatVoicesList } from '../utils/list-formatter.js';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { execFileSync } from 'child_process';
+import os from 'os';
+import {
+  KOKORO_VOICE_IDS,
+  kokoroGender,
+  ELEVENLABS_VOICES,
+} from '../services/provider-voice-catalog.js';
+import {
+  listVoices as catalogListVoices,
+  getProvider,
+} from '../services/provider-catalog.js';
+
+/**
+ * Get Piper voices from voice directory
+ */
+function getPiperVoices(voiceDir, currentVoice) {
+  const voices = [];
+
+  if (!fs.existsSync(voiceDir)) {
+    return voices;
+  }
+
+  const files = fs.readdirSync(voiceDir);
+  for (const file of files) {
+    if (file.endsWith('.onnx')) {
+      const voiceName = path.basename(file, '.onnx');
+      voices.push({
+        name: voiceName,
+        lang: extractLanguage(voiceName),
+        current: voiceName === currentVoice
+      });
+    }
+  }
+
+  return voices.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Get macOS voices using say -v ?
+ */
+function getMacOSVoices(currentVoice) {
+  const voices = [];
+
+  if (os.platform() !== 'darwin') {
+    return voices;
+  }
+
+  try {
+    const output = execFileSync('say', ['-v', '?'], { encoding: 'utf8' }); // NOSONAR - Safe: checking macOS say voices from system PATH
+    const lines = output.split('\n');
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+
+      const parts = line.trim().split(/\s+/);
+      if (parts.length >= 2) {
+        const voiceName = parts[0];
+        const lang = parts[1];
+
+        voices.push({
+          name: voiceName,
+          lang,
+          current: voiceName === currentVoice
+        });
+      }
+    }
+  } catch (error) {
+    // say command failed
+  }
+
+  return voices;
+}
+
+/**
+ * Kokoro voice ids follow `<lang><sex>_name`. The first char is the language.
+ * Map it to a human-readable language label for the listing.
+ */
+const KOKORO_LANG_LABELS = {
+  a: 'en-US', b: 'en-GB', j: 'ja', z: 'zh', e: 'es',
+  f: 'fr', h: 'hi', i: 'it', p: 'pt-BR', k: 'ko',
+};
+
+/**
+ * Get Kokoro voices from the canonical catalog (KOKORO_VOICE_IDS).
+ * Kokoro's voice set is a fixed catalog, not discovered on disk.
+ */
+function getKokoroVoices(currentVoice) {
+  return KOKORO_VOICE_IDS.map((id) => ({
+    name: id,
+    lang: KOKORO_LANG_LABELS[id[0]] || '',
+    gender: kokoroGender(id),
+    current: id === currentVoice,
+  }));
+}
+
+/**
+ * Get ElevenLabs voices from the canonical catalog (ELEVENLABS_VOICES).
+ * The listing shows the friendly name; matching against currentVoice accepts
+ * either the friendly name or the raw voice_id.
+ */
+function getElevenLabsVoices(currentVoice) {
+  return ELEVENLABS_VOICES.map((v) => ({
+    name: v.name,
+    lang: v.lang || '',
+    gender: v.gender || '',
+    current: v.name === currentVoice || v.id === currentVoice,
+  }));
+}
+
+/**
+ * Get Soprano voices from the canonical catalog. Soprano is voiceModel `single`
+ * (design §3.1): exactly one canonical voice, soprano-default — no picker.
+ */
+function getSopranoVoices(currentVoice) {
+  return catalogListVoices('soprano').map((v) => ({
+    name: v.id,
+    lang: '',
+    gender: v.gender || '',
+    current: v.id === currentVoice || currentVoice === '' || currentVoice === 'soprano',
+  }));
+}
+
+/**
+ * Extract language code from voice name
+ */
+function extractLanguage(voiceName) {
+  const match = voiceName.match(/^([a-z]{2}_[A-Z]{2})/);
+  return match ? match[1] : '';
+}
+
+/**
+ * Discovered providers list-voices enumerates HERE, each via its own platform
+ * discovery path (piper: `*.onnx` disk glob; macos: `say -v ?`). Other discovered
+ * providers (windows-piper / windows-sapi) are enumerated by the Windows lister,
+ * not this Unix/darwin CLI, so they fall to the honest "no voice list" label —
+ * preserving pre-AVI-S9.5 output. Adding a record with a static/name-to-id/single
+ * voiceModel adds a list arm for free (no edit here needed).
+ */
+const LISTABLE_DISCOVERED = new Set(['piper', 'macos']);
+
+/**
+ * Resolve a provider token to its voice list + display label by iterating the
+ * Provider Catalog (src/services/provider-catalog.js) and branching ONLY on the
+ * record's `voiceModel` — replacing the former four hardcoded per-provider
+ * equality branches (AVI-S9.5 / design row 19). Unknown tokens keep the honest
+ * "no voice list available" label from AVI-S8.1.
+ *
+ * @param {string} provider
+ * @param {string} currentVoice
+ * @param {string} voiceDir
+ * @returns {{ voices: object[], providerName: string }}
+ */
+function selectVoices(provider, currentVoice, voiceDir) {
+  const record = getProvider(provider);
+  if (!record) {
+    return { voices: [], providerName: `${provider} (no voice list available)` };
+  }
+
+  // Label preserves the pre-existing strings exactly (macOS uses "TTS", not the
+  // catalog display name "macOS Say"); all others equal record.displayName.
+  const providerName = record.id === 'macos' ? 'macOS TTS' : record.displayName;
+
+  switch (record.voiceModel) {
+    case 'static': // kokoro
+      return { voices: getKokoroVoices(currentVoice), providerName };
+    case 'name-to-id': // elevenlabs
+      return { voices: getElevenLabsVoices(currentVoice), providerName };
+    case 'single': // soprano
+      return { voices: getSopranoVoices(currentVoice), providerName };
+    case 'discovered':
+    default:
+      if (record.id === 'piper') return { voices: getPiperVoices(voiceDir, currentVoice), providerName };
+      if (record.id === 'macos') return { voices: getMacOSVoices(currentVoice), providerName };
+      // A discovered provider without a discovery path on this platform: label
+      // it honestly instead of rendering an empty list under a wrong provider.
+      return { voices: [], providerName: `${provider} (no voice list available)` };
+  }
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const args = process.argv.slice(2);
+
+  // Parse arguments
+  const provider = args[0] || 'piper';
+  const currentVoice = args[1] || '';
+  const voiceDir = args[2] || '';
+
+  const { voices, providerName } = selectVoices(provider, currentVoice, voiceDir);
+
+  // Display with boxen
+  const output = formatVoicesList(voices, {
+    provider: providerName,
+    columns: 2,
+    showUsage: true
+  });
+
+  console.log(output);
+}
+
+// Only run when invoked as a CLI (keeps selectVoices importable by tests).
+const _invokedDirectly = process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (_invokedDirectly) main();
+
+export { selectVoices, LISTABLE_DISCOVERED };