agentvibes 5.12.0 → 5.13.1

package/src/services/provider-catalog.js

@@ -0,0 +1,412 @@
+/**
+ * Provider Catalog — Layer 2 of the SSOT program (companion to the Utterance
+ * Resolver, src/services/utterance-resolver.js). See
+ * docs/architecture/provider-catalog-design.md.
+ *
+ * ONE record per provider answers the inventory question — "WHAT exists to speak
+ * with?": voice lists, defaults, membership validation, per-platform runtime,
+ * and display names. The resolver answers the orthogonal question ("HOW is this
+ * utterance spoken?"). The two layers NEVER import each other — the seam is
+ * welded by conformance assertions only (see
+ * test/unit/provider-catalog-conformance.test.js). That keeps the resolver's
+ * 433-test contract untouched.
+ *
+ * DISCIPLINE: this module is PURE data + PURE functions. No `fs`, no `env`, no
+ * clock — exactly like the resolver. Discovered providers (piper, macos, SAPI)
+ * receive their installed-voice list via injection (`{ installed }`); the
+ * catalog owns the RULE, never the I/O.
+ *
+ * SECURITY NOTE: the receiver `ALLOWED_VOICES` allowlists
+ * (clawdbot-receiver-SECURE.sh) are a SECURITY control, NOT inventory — they are
+ * deliberately narrower than this catalog and must never be unified with it.
+ *
+ * @module services/provider-catalog
+ */
+
+'use strict';
+
+/* ------------------------------------------------------------------ *
+ * Static voice data (the canonical copies; provider-voice-catalog.js
+ * re-exports these for back-compat).
+ * ------------------------------------------------------------------ */
+
+/** ElevenLabs DEFAULT-LIBRARY voices (voice_id + display metadata), available to
+ * every API key. Community/library voices that must be added to an account first
+ * are intentionally excluded so a switch can't fail at synth time. Mirrored on
+ * the shell side by .claude/hooks/elevenlabs-voices.sh (parity-guarded). */
+const ELEVENLABS_VOICES = [
+  { id: 'EXAVITQu4vr4xnSDxMaL', name: 'Sarah',   gender: 'Female', lang: 'en-US', desc: 'Mature, reassuring'      },
+  { id: 'CwhRBWXzGAHq8TQ4Fs17', name: 'Roger',   gender: 'Male',   lang: 'en-US', desc: 'Laid-back, casual'       },
+  { id: 'FGY2WhTYpPnrIDTdsKH5', name: 'Laura',   gender: 'Female', lang: 'en-US', desc: 'Enthusiast, quirky'      },
+  { id: 'IKne3meq5aSn9XLyUdCD', name: 'Charlie', gender: 'Male',   lang: 'en-AU', desc: 'Deep, confident'         },
+  { id: 'JBFqnCBsd6RMkjVDRZzb', name: 'George',  gender: 'Male',   lang: 'en-GB', desc: 'Warm storyteller'        },
+  { id: 'N2lVS1w4EtoT3dr4eOWO', name: 'Callum',  gender: 'Male',   lang: 'en-US', desc: 'Husky trickster'         },
+  { id: 'SAz9YHcvj6GT2YYXdXww', name: 'River',   gender: '',       lang: 'en-US', desc: 'Relaxed, neutral'        },
+  { id: 'SOYHLrjzK2X1ezoPC6cr', name: 'Harry',   gender: 'Male',   lang: 'en-US', desc: 'Fierce warrior'          },
+  { id: 'TX3LPaxmHKxFdv7VOQHJ', name: 'Liam',    gender: 'Male',   lang: 'en-US', desc: 'Energetic creator'       },
+  { id: 'Xb7hH8MSUJpSbSDYk0k2', name: 'Alice',   gender: 'Female', lang: 'en-GB', desc: 'Clear educator'          },
+  { id: 'XrExE9yKIg1WjnnlVkGX', name: 'Matilda', gender: 'Female', lang: 'en-US', desc: 'Knowledgable, pro'       },
+  { id: 'bIHbv24MWmeRgasZH58o', name: 'Will',    gender: 'Male',   lang: 'en-US', desc: 'Relaxed optimist'        },
+  { id: 'cgSgspJ2msm6clMCkdW9', name: 'Jessica', gender: 'Female', lang: 'en-US', desc: 'Playful, bright'         },
+  { id: 'cjVigY5qzO86Huf0OWal', name: 'Eric',    gender: 'Male',   lang: 'en-US', desc: 'Smooth, trustworthy'     },
+  { id: 'hpp4J3VqNfWAUOO0d1Us', name: 'Bella',   gender: 'Female', lang: 'en-US', desc: 'Professional, warm'      },
+  { id: 'iP95p4xoKVk53GoZ742B', name: 'Chris',   gender: 'Male',   lang: 'en-US', desc: 'Charming, down-to-earth' },
+  { id: 'nPczCjzI2devNBz1zQrb', name: 'Brian',   gender: 'Male',   lang: 'en-US', desc: 'Deep, comforting'        },
+  { id: 'onwK4e9ZLuTAKqWW03F9', name: 'Daniel',  gender: 'Male',   lang: 'en-GB', desc: 'Steady broadcaster'      },
+  { id: 'pFZP5JQG7iQjIQuC4Bku', name: 'Lily',    gender: 'Female', lang: 'en-GB', desc: 'Velvety actress'         },
+  { id: 'pNInz6obpgDQGcFmaJgB', name: 'Adam',    gender: 'Male',   lang: 'en-US', desc: 'Dominant, firm'          },
+  { id: 'pqHfZKP75CvOlQylNhV4', name: 'Bill',    gender: 'Male',   lang: 'en-US', desc: 'Wise, mature'            },
+];
+
+/** Kokoro voice ids. Gender is encoded in the id: the 2nd char is f|m. */
+const KOKORO_VOICE_IDS = [
+  // American English
+  'af_heart','af_alloy','af_aoede','af_bella','af_jessica','af_kore','af_nicole','af_nova','af_river','af_sarah','af_sky',
+  'am_adam','am_echo','am_eric','am_fenrir','am_liam','am_michael','am_onyx','am_puck',
+  // British English
+  'bf_alice','bf_emma','bf_isabella','bf_lily',
+  'bm_daniel','bm_fable','bm_george','bm_lewis',
+  // Japanese
+  'jf_alpha','jf_gongitsune','jf_nezumi','jf_tebukuro','jm_kumo',
+  // Mandarin Chinese
+  'zf_xiaobei','zf_xiaoni','zf_xiaoxiao','zf_xiaoyi','zm_yunxi','zm_yunxia','zm_yunyang',
+  // Spanish
+  'ef_dora','em_alex','em_santa',
+  // French
+  'ff_siwis',
+  // Hindi
+  'hf_alpha','hm_omega',
+  // Italian
+  'if_sara','im_nicola',
+  // Brazilian Portuguese
+  'pf_dora','pm_alex','pm_santa',
+  // Korean
+  'kf_alpha','km_hyunsu',
+];
+
+/**
+ * Infer a Kokoro voice's gender from its id. Kokoro ids follow `<lang><sex>_name`
+ * where the 2nd character is `f` (female) or `m` (male).
+ * @param {string} id
+ * @returns {'Female'|'Male'|''}
+ */
+function kokoroGender(id) {
+  const c = typeof id === 'string' && id.length > 1 ? id[1].toLowerCase() : '';
+  if (c === 'f') return 'Female';
+  if (c === 'm') return 'Male';
+  return '';
+}
+
+/* ------------------------------------------------------------------ *
+ * Voice-model validation rules (pure). Each returns { ok, canonical, reason }.
+ * ------------------------------------------------------------------ */
+
+/** Piper-family voice shape: `en_US-lessac-medium` or a `model::Speaker` form. */
+const PIPER_VOICE_SHAPE = /^[a-z]{2,3}_[A-Z]{2}-/;
+/** Raw ElevenLabs voice_id shape (preserves elevenlabs-voices.sh:66 semantics). */
+const ELEVENLABS_ID_SHAPE = /^[A-Za-z0-9]{20}$/;
+
+/* ------------------------------------------------------------------ *
+ * The seven canonical ProviderRecords.
+ *
+ * `aliases` are spellings that resolve to THIS record via getProvider()
+ * (e.g. windows-sapi ← 'sapi'). `engineId` is the resolver ENGINES value
+ * ('sapi' for windows-sapi, 'piper' for windows-piper); the derived
+ * engineAliasTable() mirrors the resolver's ENGINE_ALIASES.
+ * ------------------------------------------------------------------ */
+
+const RECORDS = [
+  {
+    id: 'soprano',
+    engineId: 'soprano',
+    aliases: [],
+    displayName: 'Soprano TTS',
+    voiceModel: 'single',
+    voices: ['soprano-default'],
+    defaultVoice: 'soprano-default',
+    runtime: { unix: 'play-tts-soprano.sh', windows: 'play-tts-soprano.ps1', darwinOnly: false },
+    requires: 'pip',
+  },
+  {
+    id: 'piper',
+    engineId: 'piper',
+    aliases: [],
+    displayName: 'Piper TTS',
+    voiceModel: 'discovered',
+    voices: null, // discovered on disk (*.onnx glob)
+    defaultVoice: 'en_US-lessac-medium', // preferred fallback, NOT a guaranteed install
+    runtime: { unix: 'play-tts-piper.sh', windows: null, darwinOnly: false }, // Windows uses windows-piper
+    requires: 'pip',
+  },
+  {
+    id: 'kokoro',
+    engineId: 'kokoro',
+    aliases: [],
+    displayName: 'Kokoro TTS',
+    voiceModel: 'static',
+    voices: KOKORO_VOICE_IDS,
+    defaultVoice: 'af_heart',
+    runtime: { unix: 'play-tts-kokoro.sh', windows: 'play-tts-kokoro.ps1', darwinOnly: false },
+    requires: 'pip',
+  },
+  {
+    id: 'elevenlabs',
+    engineId: 'elevenlabs',
+    aliases: [],
+    displayName: 'ElevenLabs',
+    voiceModel: 'name-to-id',
+    voices: ELEVENLABS_VOICES,
+    defaultVoice: 'Sarah',
+    runtime: { unix: 'play-tts-elevenlabs.sh', windows: null, darwinOnly: false }, // ← no ps1 runtime; the contradiction, now data
+    requires: 'api-key',
+  },
+  {
+    id: 'macos',
+    engineId: 'macos',
+    aliases: ['macos-say', 'say'],
+    displayName: 'macOS Say',
+    voiceModel: 'discovered',
+    voices: null, // `say -v ?`
+    defaultVoice: 'Samantha',
+    runtime: { unix: 'play-tts-macos.sh', windows: null, darwinOnly: true },
+    requires: 'builtin',
+  },
+  {
+    id: 'windows-sapi',
+    engineId: 'sapi',
+    aliases: ['sapi'],
+    displayName: 'Windows SAPI',
+    voiceModel: 'discovered',
+    voices: null, // System.Speech
+    defaultVoice: '', // system default
+    runtime: { unix: null, windows: 'play-tts-sapi.ps1', darwinOnly: false },
+    requires: 'builtin',
+  },
+  {
+    id: 'windows-piper',
+    engineId: 'piper',
+    aliases: ['piper'], // on Windows, bare 'piper' forwards to windows-piper
+    displayName: 'Piper TTS',
+    voiceModel: 'discovered',
+    voices: null, // same *.onnx models as piper
+    defaultVoice: 'en_US-lessac-medium',
+    runtime: { unix: null, windows: 'play-tts-windows-piper.ps1', darwinOnly: false },
+    requires: 'exe',
+  },
+];
+
+// Lookup indexes (built once).
+const _BY_ID = new Map();
+const _BY_ALIAS = new Map();
+for (const r of RECORDS) {
+  _BY_ID.set(r.id, r);
+}
+for (const r of RECORDS) {
+  for (const a of r.aliases) {
+    // Exact-id spellings always win, so never let an alias shadow a real id.
+    if (!_BY_ID.has(a) && !_BY_ALIAS.has(a)) _BY_ALIAS.set(a, r);
+  }
+}
+
+/** Normalize an id-or-alias to a lowercase key. */
+function _norm(idOrAlias) {
+  return typeof idOrAlias === 'string' ? idOrAlias.trim().toLowerCase() : '';
+}
+
+/* ------------------------------------------------------------------ *
+ * Public API (design §3.2). All entries are alias-normalizing.
+ * ------------------------------------------------------------------ */
+
+/**
+ * @param {string} idOrAlias
+ * @returns {object|null} the ProviderRecord, or null if unknown.
+ */
+function getProvider(idOrAlias) {
+  const key = _norm(idOrAlias);
+  if (!key) return null;
+  return _BY_ID.get(key) || _BY_ALIAS.get(key) || null;
+}
+
+/** @returns {object[]} all seven records (fresh array; records are shared). */
+function listProviders() {
+  return RECORDS.slice();
+}
+
+/**
+ * Is a provider playable on `platform`?
+ *   - 'windows' → has a Windows runtime script.
+ *   - 'darwin'  → has a Unix runtime script (darwin runs the .sh players).
+ *   - 'unix'    → has a Unix runtime AND is not darwin-only (i.e. Linux).
+ * @param {string} idOrAlias
+ * @param {'unix'|'windows'|'darwin'} platform
+ * @returns {boolean}
+ */
+function isAvailable(idOrAlias, platform) {
+  const r = getProvider(idOrAlias);
+  if (!r) return false;
+  if (platform === 'windows') return r.runtime.windows !== null;
+  if (platform === 'darwin') return r.runtime.unix !== null;
+  return r.runtime.unix !== null && !r.runtime.darwinOnly; // 'unix' == generic Linux
+}
+
+/**
+ * @param {'unix'|'windows'|'darwin'} platform
+ * @returns {object[]} records available on that platform.
+ */
+function providersFor(platform) {
+  return RECORDS.filter((r) => isAvailable(r.id, platform));
+}
+
+/**
+ * List a provider's voices as `{ id, name?, gender, lang? }` entries. Discovered
+ * providers require an injected `installed` list (else an empty array).
+ * @param {string} idOrAlias
+ * @param {{installed?: string[]}} [opts]
+ * @returns {Array<{id: string, name?: string, gender: string, lang?: string}>}
+ */
+function listVoices(idOrAlias, { installed } = {}) {
+  const r = getProvider(idOrAlias);
+  if (!r) return [];
+  switch (r.voiceModel) {
+    case 'static': // kokoro
+      return r.voices.map((id) => ({ id, gender: kokoroGender(id) }));
+    case 'name-to-id': // elevenlabs
+      return r.voices.map((v) => ({ id: v.id, name: v.name, gender: v.gender || '', lang: v.lang }));
+    case 'single': // soprano
+      return r.voices.map((id) => ({ id, gender: '' }));
+    case 'discovered': // piper / macos / windows-sapi / windows-piper
+    default:
+      if (Array.isArray(installed)) return installed.map((id) => ({ id, gender: '' }));
+      return [];
+  }
+}
+
+/**
+ * @param {string} idOrAlias
+ * @returns {string} the provider's default voice ('' for windows-sapi = system default).
+ */
+function defaultVoice(idOrAlias) {
+  const r = getProvider(idOrAlias);
+  return r ? r.defaultVoice : '';
+}
+
+/**
+ * Validate a voice for a provider. STRICT membership at config-write time
+ * (typos never reach voice.txt). Returns `{ ok, canonical, reason }` — never a
+ * bare boolean — so every rejection carries a message and the accepted spelling
+ * is normalized ONCE.
+ *
+ * @param {string} idOrAlias
+ * @param {string} voice
+ * @param {{installed?: string[], allowUnlisted?: boolean}} [opts]
+ *   `allowUnlisted` expresses the AGENTVIBES_ALLOW_UNLISTED_VOICE escape hatch —
+ *   the catalog never reads env; consumers pass the flag (design §3.3). It relaxes
+ *   MEMBERSHIP, not shape.
+ * @returns {{ok: boolean, canonical: string|null, reason: string}}
+ */
+function validateVoice(idOrAlias, voice, { installed, allowUnlisted = false } = {}) {
+  const r = getProvider(idOrAlias);
+  if (!r) return { ok: false, canonical: null, reason: `Unknown provider: ${idOrAlias}` };
+  const raw = typeof voice === 'string' ? voice.trim() : '';
+
+  switch (r.voiceModel) {
+    case 'static': { // kokoro — case-fold, exact membership
+      const folded = raw.toLowerCase();
+      if (r.voices.includes(folded)) return { ok: true, canonical: folded, reason: '' };
+      if (allowUnlisted && folded) return { ok: true, canonical: folded, reason: '' };
+      return { ok: false, canonical: null, reason: `"${voice}" is not a known ${r.displayName} voice` };
+    }
+    case 'name-to-id': { // elevenlabs — case-insensitive name → id, OR raw 20-char id
+      const lc = raw.toLowerCase();
+      const byName = r.voices.find((v) => v.name.toLowerCase() === lc);
+      if (byName) return { ok: true, canonical: byName.id, reason: '' };
+      if (ELEVENLABS_ID_SHAPE.test(raw)) return { ok: true, canonical: raw, reason: '' };
+      return { ok: false, canonical: null, reason: `"${voice}" is not a known ElevenLabs voice name or id` };
+    }
+    case 'single': { // soprano — '', 'soprano', 'soprano-default' → canonical 'soprano-default'
+      const lc = raw.toLowerCase();
+      if (lc === '' || lc === r.id || lc === r.defaultVoice) {
+        return { ok: true, canonical: r.defaultVoice, reason: '' };
+      }
+      return { ok: false, canonical: null, reason: `${r.displayName} has a single voice (${r.defaultVoice})` };
+    }
+    case 'discovered': // piper / macos / windows-sapi / windows-piper
+    default: {
+      const isPiperFamily = r.engineId === 'piper';
+      if (Array.isArray(installed)) {
+        if (installed.includes(raw)) return { ok: true, canonical: raw, reason: '' };
+        if (!allowUnlisted) {
+          return { ok: false, canonical: null, reason: `"${voice}" is not an installed ${r.displayName} voice` };
+        }
+        // allowUnlisted: fall through to shape/permissive check
+      }
+      if (isPiperFamily) {
+        if (PIPER_VOICE_SHAPE.test(raw) || raw.includes('::')) return { ok: true, canonical: raw, reason: '' };
+        return { ok: false, canonical: null, reason: `"${voice}" is not a valid Piper voice id` };
+      }
+      // macos / windows-sapi: permissive when no list is available; '' = system default.
+      if (raw === '' && r.defaultVoice === '') return { ok: true, canonical: '', reason: '' };
+      if (raw) return { ok: true, canonical: raw, reason: '' };
+      return { ok: false, canonical: null, reason: `Empty voice for ${r.displayName}` };
+    }
+  }
+}
+
+/**
+ * @param {string} idOrAlias
+ * @returns {string} a human display name, or the input unchanged if unknown
+ *   (mirrors provider-validator.getProviderDisplayName's passthrough).
+ */
+function displayName(idOrAlias) {
+  const r = getProvider(idOrAlias);
+  if (r) return r.displayName;
+  return typeof idOrAlias === 'string' ? idOrAlias : '';
+}
+
+/**
+ * Derived alias→engine table, built to MIRROR the resolver's ENGINE_ALIASES
+ * (utterance-resolver.js:52-57). A record whose id differs from its engineId
+ * contributes id→engineId; each non-identity alias contributes alias→engineId.
+ * Conformance group 6 asserts this deep-equals the resolver's table.
+ * @returns {Record<string,string>}
+ */
+function engineAliasTable() {
+  const table = {};
+  for (const r of RECORDS) {
+    if (r.id !== r.engineId) table[r.id] = r.engineId;
+    for (const a of r.aliases) {
+      if (a !== r.engineId) table[a] = r.engineId;
+    }
+  }
+  return table;
+}
+
+export {
+  getProvider,
+  listProviders,
+  providersFor,
+  isAvailable,
+  listVoices,
+  defaultVoice,
+  validateVoice,
+  displayName,
+  engineAliasTable,
+  kokoroGender,
+  ELEVENLABS_VOICES,
+  KOKORO_VOICE_IDS,
+};
+
+export default {
+  getProvider,
+  listProviders,
+  providersFor,
+  isAvailable,
+  listVoices,
+  defaultVoice,
+  validateVoice,
+  displayName,
+  engineAliasTable,
+  kokoroGender,
+  ELEVENLABS_VOICES,
+  KOKORO_VOICE_IDS,
+};

package/src/services/provider-voice-catalog.js

@@ -1,87 +1,55 @@
 /**
- * Provider voice catalogs — single source of truth for the static voice lists
- * of the cloud/neural providers, plus a helper that returns the voice pool for
- * whichever provider is currently active.
+ * Provider voice catalogs — BACK-COMPAT SHIM.
  *
- * Piper voices are NOT listed here (they are discovered on disk via
- * scanInstalledVoices); this module covers the providers whose voices are a
- * fixed catalog: ElevenLabs and Kokoro. Single-voice providers (e.g. soprano)
- * resolve to a single synthetic entry.
+ * The canonical source of provider voice data is now
+ * `src/services/provider-catalog.js` (the Provider Catalog, SSOT Layer 2). This
+ * module re-exports the static voice lists (`ELEVENLABS_VOICES`,
+ * `KOKORO_VOICE_IDS`) and the gender helper from the catalog, and keeps the
+ * `voicesForProvider()` convenience used by BMAD gender-aware auto-assignment.
+ *
+ * Kept as a shim so existing importers (and test/unit/provider-voice-catalog.test.js)
+ * continue to work unmodified.
  *
  * @module services/provider-voice-catalog
  */
 
 import { isSingleVoiceProvider } from './agent-voice-store.js';
+import {
+  ELEVENLABS_VOICES,
+  KOKORO_VOICE_IDS,
+  kokoroGender,
+} from './provider-catalog.js';
+
+export { ELEVENLABS_VOICES, KOKORO_VOICE_IDS, kokoroGender };
 
-/** ElevenLabs library voices (voice_id + display metadata). */
-export const ELEVENLABS_VOICES = [
-  { id: 'EXAVITQu4vr4xnSDxMaL', name: 'Sarah',   gender: 'Female', lang: 'en-US', desc: 'Mature, reassuring'      },
-  { id: 'CwhRBWXzGAHq8TQ4Fs17', name: 'Roger',   gender: 'Male',   lang: 'en-US', desc: 'Laid-back, casual'       },
-  { id: 'FGY2WhTYpPnrIDTdsKH5', name: 'Laura',   gender: 'Female', lang: 'en-US', desc: 'Enthusiast, quirky'      },
-  { id: 'IKne3meq5aSn9XLyUdCD', name: 'Charlie', gender: 'Male',   lang: 'en-AU', desc: 'Deep, confident'         },
-  { id: 'JBFqnCBsd6RMkjVDRZzb', name: 'George',  gender: 'Male',   lang: 'en-GB', desc: 'Warm storyteller'        },
-  { id: 'N2lVS1w4EtoT3dr4eOWO', name: 'Callum',  gender: 'Male',   lang: 'en-US', desc: 'Husky trickster'         },
-  { id: 'SAz9YHcvj6GT2YYXdXww', name: 'River',   gender: '',       lang: 'en-US', desc: 'Relaxed, neutral'        },
-  { id: 'SOYHLrjzK2X1ezoPC6cr', name: 'Harry',   gender: 'Male',   lang: 'en-US', desc: 'Fierce warrior'          },
-  { id: 'TX3LPaxmHKxFdv7VOQHJ', name: 'Liam',    gender: 'Male',   lang: 'en-US', desc: 'Energetic creator'       },
-  { id: 'Xb7hH8MSUJpSbSDYk0k2', name: 'Alice',   gender: 'Female', lang: 'en-GB', desc: 'Clear educator'          },
-  { id: 'XrExE9yKIg1WjnnlVkGX', name: 'Matilda', gender: 'Female', lang: 'en-US', desc: 'Knowledgable, pro'       },
-  { id: 'bIHbv24MWmeRgasZH58o', name: 'Will',    gender: 'Male',   lang: 'en-US', desc: 'Relaxed optimist'        },
-  { id: 'cgSgspJ2msm6clMCkdW9', name: 'Jessica', gender: 'Female', lang: 'en-US', desc: 'Playful, bright'         },
-  { id: 'cjVigY5qzO86Huf0OWal', name: 'Eric',    gender: 'Male',   lang: 'en-US', desc: 'Smooth, trustworthy'     },
-  { id: 'hpp4J3VqNfWAUOO0d1Us', name: 'Bella',   gender: 'Female', lang: 'en-US', desc: 'Professional, warm'      },
-  { id: 'iP95p4xoKVk53GoZ742B', name: 'Chris',   gender: 'Male',   lang: 'en-US', desc: 'Charming, down-to-earth' },
-  { id: 'nPczCjzI2devNBz1zQrb', name: 'Brian',   gender: 'Male',   lang: 'en-US', desc: 'Deep, comforting'        },
-  { id: 'onwK4e9ZLuTAKqWW03F9', name: 'Daniel',  gender: 'Male',   lang: 'en-GB', desc: 'Steady broadcaster'      },
-  { id: 'pFZP5JQG7iQjIQuC4Bku', name: 'Lily',    gender: 'Female', lang: 'en-GB', desc: 'Velvety actress'         },
-  { id: 'pNInz6obpgDQGcFmaJgB', name: 'Adam',    gender: 'Male',   lang: 'en-US', desc: 'Dominant, firm'          },
-  { id: 'pqHfZKP75CvOlQylNhV4', name: 'Bill',    gender: 'Male',   lang: 'en-US', desc: 'Wise, mature'            },
-  // ── Added from the ElevenLabs voice library (raw library voice_ids) ───────
-  { id: 'HBDoL4wkcalemIO0nUAu', name: 'Emily',   gender: 'Female', lang: 'en-GB', desc: 'RPG, immersive'    },
-  { id: 'Mtmp3KhFIjYpWYRycDe3', name: 'John',    gender: 'Male',   lang: 'en-US', desc: 'Raspy surfer'      },
-  { id: '8kgj5469z1URcH4MB2G4', name: 'Sakuya',  gender: 'Female', lang: 'en-US', desc: 'Cheerful anime'    },
-  { id: '2ajXGJNYBR0iNHpS4VZb', name: 'Rob',     gender: 'Male',   lang: 'en-GB', desc: 'Tough, gritty'     },
-  { id: 'mMdTuD2nnFiCH88UdXSb', name: 'Jane',    gender: 'Female', lang: 'en-US', desc: 'Cinematic villain' },
+/**
+ * Curated built-in voices for the OS-native "discovered" providers (Windows SAPI,
+ * macOS `say`). Their real voices live on the target device — for a remote
+ * receiver we cannot enumerate them from here — so these standard voices (shipped
+ * by default on Windows 10/11 and macOS) give the picker an honest, selectable
+ * list. The `id` is the exact name the player passes to SelectVoice / `say -v`;
+ * if the receiver lacks one it falls back to the system default (benign).
+ *
+ * Verified against a real Windows 11 install (System.Speech GetInstalledVoices).
+ * The receiver remains authoritative — this is UI convenience, not inventory SSOT.
+ */
+const WINDOWS_SAPI_VOICES = [
+  { id: 'Microsoft David Desktop', name: 'David (Desktop)', gender: 'Male',   lang: 'en-US' },
+  { id: 'Microsoft Zira Desktop',  name: 'Zira (Desktop)',  gender: 'Female', lang: 'en-US' },
+  { id: 'Microsoft David',         name: 'David',           gender: 'Male',   lang: 'en-US' },
+  { id: 'Microsoft Mark',          name: 'Mark',            gender: 'Male',   lang: 'en-US' },
+  { id: 'Microsoft Zira',          name: 'Zira',            gender: 'Female', lang: 'en-US' },
 ];
 
-/** Kokoro voice ids. Gender is encoded in the id: the 2nd char is f|m. */
-export const KOKORO_VOICE_IDS = [
-  // American English
-  'af_heart','af_alloy','af_aoede','af_bella','af_jessica','af_kore','af_nicole','af_nova','af_river','af_sarah','af_sky',
-  'am_adam','am_echo','am_eric','am_fenrir','am_liam','am_michael','am_onyx','am_puck',
-  // British English
-  'bf_alice','bf_emma','bf_isabella','bf_lily',
-  'bm_daniel','bm_fable','bm_george','bm_lewis',
-  // Japanese
-  'jf_alpha','jf_gongitsune','jf_nezumi','jf_tebukuro','jm_kumo',
-  // Mandarin Chinese
-  'zf_xiaobei','zf_xiaoni','zf_xiaoxiao','zf_xiaoyi','zm_yunxi','zm_yunxia','zm_yunyang',
-  // Spanish
-  'ef_dora','em_alex','em_santa',
-  // French
-  'ff_siwis',
-  // Hindi
-  'hf_alpha','hm_omega',
-  // Italian
-  'if_sara','im_nicola',
-  // Brazilian Portuguese
-  'pf_dora','pm_alex','pm_santa',
-  // Korean
-  'kf_alpha','km_hyunsu',
+const MACOS_VOICES = [
+  { id: 'Samantha', name: 'Samantha', gender: 'Female', lang: 'en-US' },
+  { id: 'Alex',     name: 'Alex',     gender: 'Male',   lang: 'en-US' },
+  { id: 'Daniel',   name: 'Daniel',   gender: 'Male',   lang: 'en-GB' },
+  { id: 'Karen',    name: 'Karen',    gender: 'Female', lang: 'en-AU' },
+  { id: 'Moira',    name: 'Moira',    gender: 'Female', lang: 'en-IE' },
 ];
 
-/**
- * Infer a Kokoro voice's gender from its id. Kokoro ids follow `<lang><sex>_name`
- * where the 2nd character is `f` (female) or `m` (male).
- * @param {string} id
- * @returns {'Female'|'Male'|''}
- */
-export function kokoroGender(id) {
-  const c = typeof id === 'string' && id.length > 1 ? id[1].toLowerCase() : '';
-  if (c === 'f') return 'Female';
-  if (c === 'm') return 'Male';
-  return '';
-}
+export { WINDOWS_SAPI_VOICES, MACOS_VOICES };
 
 /**
  * Return the voice pool for the currently-active provider as `{ id, gender }`
@@ -108,6 +76,17 @@ export function voicesForProvider(provider, { scanInstalledVoices, getVoiceMeta
     return ELEVENLABS_VOICES.map(v => ({ id: v.id, gender: v.gender || '' }));
   }
 
+  // OS-native discovered providers: their voices live on the target device (the
+  // receiver in remote mode), so they can't be scanned here. Return the curated
+  // built-in list instead of falling through to the Piper disk scan (which would
+  // mislabel them as Piper voices).
+  if (p === 'sapi' || p === 'windows-sapi') {
+    return WINDOWS_SAPI_VOICES.map(v => ({ id: v.id, gender: v.gender || '' }));
+  }
+  if (p === 'macos' || p === 'macos-say' || p === 'say') {
+    return MACOS_VOICES.map(v => ({ id: v.id, gender: v.gender || '' }));
+  }
+
   // Single-voice providers (e.g. soprano): one synthetic entry named after the
   // provider — every agent ends up sharing it, which is correct for these.
   if (isSingleVoiceProvider(p)) {
@@ -123,4 +102,4 @@ export function voicesForProvider(provider, { scanInstalledVoices, getVoiceMeta
   return [];
 }
 
-export default { ELEVENLABS_VOICES, KOKORO_VOICE_IDS, kokoroGender, voicesForProvider };
+export default { ELEVENLABS_VOICES, KOKORO_VOICE_IDS, WINDOWS_SAPI_VOICES, MACOS_VOICES, kokoroGender, voicesForProvider };

package/src/services/tts-engine-service.js

@@ -53,6 +53,22 @@ export function getAvailableEngines() {
   return TTS_ENGINES.filter(e => !e.platform || e.platform === process.platform);
 }
 
+/** Is this engine runnable on the current OS? (Native engines are platform-bound.) */
+export function isEngineSupported(engineId) {
+  const e = TTS_ENGINES.find(x => x.id === engineId);
+  return !!e && (!e.platform || e.platform === process.platform);
+}
+
+/**
+ * Every engine, each tagged with `supported` for the current platform. Unlike
+ * getAvailableEngines() (which hides off-platform engines), this lists them all
+ * so the picker can show e.g. Windows SAPI greyed "(Not supported)" on Linux
+ * instead of appearing to be missing.
+ */
+export function getAllEngines() {
+  return TTS_ENGINES.map(e => ({ ...e, supported: !e.platform || e.platform === process.platform }));
+}
+
 export function checkEngineInstalled(engineId) {
   const engine = TTS_ENGINES.find(e => e.id === engineId);
   if (!engine) return false;
@@ -110,6 +126,19 @@ export function checkEngineInstalled(engineId) {
   return false;
 }
 
+/**
+ * Map a picker engine id to the provider name the SSH-remote sender + receiver
+ * understand. play-tts-ssh-remote.sh validates
+ * piper|soprano|macos|windows-sapi|kokoro|elevenlabs, but the picker/config use
+ * 'sapi' and 'macos-say'. This is the single translation point.
+ * @param {string} engineId
+ * @returns {string} receiver/sender provider name
+ */
+const RECEIVER_PROVIDER_MAP = { sapi: 'windows-sapi', 'macos-say': 'macos' };
+export function receiverProviderId(engineId) {
+  return RECEIVER_PROVIDER_MAP[engineId] || engineId;
+}
+
 export function getEngineStatuses() {
   return getAvailableEngines().map(e => ({
     ...e,