@agfpd/voice-connect 0.1.11

package/src/profile.mjs

@@ -0,0 +1,165 @@
+/**
+ * Caller voice resolution from the IAPeer profiles.
+ *
+ * Voice is an agent INTERFACE (like its telegram bot), so it lives in the
+ * caller's peer profile under `interfaces.voice`, keyed by the FULL model name
+ * as used by the API — self-documenting and robust to model swaps:
+ *
+ *   interfaces.voice = {
+ *     "gemini-3.1-flash-tts-preview": "<voice>",
+ *     "supertonic-3": "<voice>"
+ *   }
+ *
+ * SOURCE OF TRUTH is the per-cwd profile `<cwd>/.iapeer/peer-profile.json` — the
+ * IAP code is explicit that the host index ~/.iapeer/peers-profiles.json is a
+ * DERIVED artifact regenerated from per-cwd profiles on connect/upsert, so it
+ * can lag. Voice is therefore read from the per-cwd profile; the host index is
+ * used only to look up the caller's stable `cwd` (the peer env carries
+ * PEER_PERSONALITY but not PEER_CWD).
+ *
+ * Resolution of the voice map:
+ *   1. PEER_PERSONALITY → host index entry → its `cwd`.
+ *   2. Read `<cwd>/.iapeer/peer-profile.json` (source of truth). If it is
+ *      readable+parseable, its `interfaces.voice` (or {} when the field is
+ *      absent — "no voice set") is authoritative; we do NOT fall back to the
+ *      index, which could carry a stale value.
+ *   3. Only if the per-cwd profile is UNAVAILABLE (missing / empty / unparseable)
+ *      do we defensively fall back to the host index entry's `interfaces.voice`.
+ *   4. Otherwise {} — the caller uses the built-in defaults.
+ *
+ * Reading the field is decoupled from populating it (the operator fills profiles
+ * separately).
+ */
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+function registryPath() {
+  return process.env.PEER_VOICE_PEERS_PROFILES
+    || join(homedir(), '.iapeer', 'peers-profiles.json');
+}
+
+/** The host index entry for a personality, or null. Real shape:
+ *  { version, peers: [ { personality, cwd, ..., interfaces } ] }. A map keyed by
+ *  personality is also accepted defensively. */
+function indexEntry(personality) {
+  let registry;
+  try {
+    registry = JSON.parse(readFileSync(registryPath(), 'utf8'));
+  } catch {
+    return null;
+  }
+  if (!registry || typeof registry !== 'object') return null;
+  const peers = registry.peers != null ? registry.peers : registry;
+  if (Array.isArray(peers)) {
+    return peers.find(p => p && p.personality === personality) || null;
+  }
+  if (peers && typeof peers === 'object') return peers[personality] || null;
+  return null;
+}
+
+function voiceOf(entry) {
+  const v = entry && entry.interfaces && entry.interfaces.voice;
+  return v && typeof v === 'object' ? v : null;
+}
+
+/**
+ * The peer profile at the PROCESS's own cwd, or null. Both the claude and the
+ * codex MCP launchers start this server with cwd = the calling peer's directory
+ * (verified live 2026-06-12: claude/boris and codex/linus children both had
+ * cwd ~/Peers/<peer>), so `<cwd>/.iapeer/peer-profile.json` IS the caller's
+ * source-of-truth profile.
+ * @returns {object|null}
+ */
+function cwdProfile() {
+  let profile;
+  try {
+    profile = JSON.parse(
+      readFileSync(join(process.cwd(), '.iapeer', 'peer-profile.json'), 'utf8'),
+    );
+  } catch {
+    return null;
+  }
+  return profile && typeof profile === 'object' ? profile : null;
+}
+
+/**
+ * The calling peer's personality, or null.
+ *
+ * Ladder: PEER_PERSONALITY env → the cwd profile's `personality`. The env var
+ * is how claude sessions identify the caller, but the codex MCP launcher does
+ * NOT propagate parent env to MCP children (verified live 2026-06-12: the codex
+ * parent had PEER_PERSONALITY/PEER_IDENTITY/PEER_RUNTIME, its MCP child had
+ * none, while manifest env did arrive) — so in codex sessions the identity is
+ * recovered from the cwd profile instead.
+ * @returns {string|null}
+ */
+export function callerPersonality() {
+  const env = process.env.PEER_PERSONALITY;
+  if (env && env.trim()) return env.trim();
+  const p = cwdProfile();
+  const own = p && typeof p.personality === 'string' ? p.personality.trim() : '';
+  return own || null;
+}
+
+/**
+ * Read `interfaces.voice` from a per-cwd profile.
+ * @returns {{available: boolean, voice: Record<string,string>}}
+ *   available=false → the profile file is missing / empty / unparseable
+ *   (caller should fall back to the index); available=true → the source of
+ *   truth was read (voice may be {} = no voice set, which is authoritative).
+ */
+function perCwdVoice(cwd) {
+  if (!cwd) return { available: false, voice: {} };
+  let profile;
+  try {
+    profile = JSON.parse(readFileSync(join(cwd, '.iapeer', 'peer-profile.json'), 'utf8'));
+  } catch {
+    return { available: false, voice: {} };
+  }
+  if (!profile || typeof profile !== 'object') return { available: false, voice: {} };
+  return { available: true, voice: voiceOf(profile) || {} };
+}
+
+/**
+ * The calling peer's `interfaces.voice` map (model-name → voice), or {}.
+ * @param {string} [personality] override the env-derived caller identity (tests)
+ * @returns {Record<string,string>}
+ */
+export function callerVoiceMap(personality = process.env.PEER_PERSONALITY) {
+  if (!personality) {
+    // No env identity (codex MCP children — parent env is not propagated):
+    // the cwd profile is the caller's per-cwd source of truth, so read the
+    // voice straight from it — no index hop, personality and voice can never
+    // disagree. cwd not a peer dir → null → {} (built-in defaults), as before.
+    const p = cwdProfile();
+    return p ? (voiceOf(p) || {}) : {};
+  }
+  const entry = indexEntry(personality);
+
+  // 1. Source of truth: the per-cwd profile (cwd looked up from the index).
+  const perCwd = perCwdVoice(entry && entry.cwd);
+  if (perCwd.available) return perCwd.voice;
+
+  // 2. Defensive: per-cwd unavailable → host index entry's voice.
+  return voiceOf(entry) || {};
+}
+
+/**
+ * Resolve the voice for a model, applying the override/profile/default ladder.
+ * @param {object} a
+ * @param {string}  a.modelName        full model name (the interfaces.voice key)
+ * @param {string}  a.def              built-in default voice for this model
+ * @param {boolean} a.applyOverride    whether the explicit override applies here
+ *                                     (true only for the call's PRIMARY engine —
+ *                                     an override must not leak across a fallback)
+ * @param {string}  [a.override]       explicit voice argument
+ * @param {Record<string,string>} a.voiceMap caller's interfaces.voice
+ * @returns {{voice: string, source: 'override'|'profile'|'default'}}
+ */
+export function resolveVoice({ modelName, def, applyOverride, override, voiceMap }) {
+  if (applyOverride && override) return { voice: override, source: 'override' };
+  const fromProfile = voiceMap && voiceMap[modelName];
+  if (fromProfile) return { voice: fromProfile, source: 'profile' };
+  return { voice: def, source: 'default' };
+}

package/src/providers.mjs

@@ -0,0 +1,210 @@
+/**
+ * TTS providers — the four engines behind one uniform contract, plus the
+ * declarative cascade table that the router runs.
+ *
+ * A provider is data + one method:
+ *   {
+ *     name, model, defaultVoice,
+ *     capabilities: { style, langs, streaming },   // first-class, declared up front
+ *     isFallbackError?(err): boolean,              // known can't-serve → advance cascade
+ *     async synthesize(ctx): { pcm, voice, lang?, finishReason? },
+ *   }
+ * ctx carries { text, style, personality, tmpDir, voice?, lang? }. Each provider
+ * encapsulates its own quirk: Gemini mints the per-peer F5 ref on success, F5
+ * loads that ref and decodes wav→pcm, Supertonic decodes wav→pcm. Adding an
+ * engine = adding one object here; the router and voice.mjs stay untouched.
+ *
+ * Idea lineage (voice-gateway research): base class with one synth method
+ * (pipecat/livekit) + Capabilities as a first-class object (livekit).
+ */
+import { join } from 'node:path';
+import {
+  geminiTTS,
+  GeminiQuotaError,
+  GeminiNoKeyError,
+  GeminiTruncatedError,
+  GeminiUnavailableError,
+  DEFAULT_GEMINI_VOICE,
+  GEMINI_MODEL,
+} from './engines/gemini.mjs';
+import {
+  gptAudioTTS,
+  GptAudioQuotaError,
+  GptAudioNoKeyError,
+  GptAudioUnavailableError,
+  DEFAULT_GPTAUDIO_VOICE,
+  GPTAUDIO_MODEL,
+} from './engines/gptaudio.mjs';
+import { f5TTS, F5UnavailableError, DEFAULT_F5_VOICE, F5_MODEL } from './engines/f5.mjs';
+import {
+  supertonicTTS,
+  DEFAULT_SUPERTONIC_VOICE,
+  SUPERTONIC_MODEL,
+} from './engines/supertonic.mjs';
+import { decodeToPcmBuffer } from './audio.mjs';
+import { saveRef, loadRef } from './ref.mjs';
+import { speachesSTT, SpeachesUnavailableError, sttEndpoint } from './engines/speaches.mjs';
+import { mlxWhisperSTT } from './engines/mlxwhisper.mjs';
+
+/** Gemini 3.1 Flash TTS — cloud primary, ru+en in one pass, supports style. */
+export const gemini = {
+  name: 'gemini',
+  model: GEMINI_MODEL,
+  defaultVoice: DEFAULT_GEMINI_VOICE,
+  capabilities: { style: true, langs: 'any', streaming: false },
+  isFallbackError: (e) =>
+    e instanceof GeminiQuotaError ||
+    e instanceof GeminiNoKeyError ||
+    e instanceof GeminiTruncatedError ||
+    e instanceof GeminiUnavailableError,
+  // `deps` is a test seam (engine + ref-store fns); defaults are the real
+  // modules, so the router's single-arg call is unchanged. Same pattern as
+  // server.mjs's injectable {voice, dispatch, transcribe}.
+  async synthesize({ text, voice, style, personality }, deps = {}) {
+    const tts = deps.tts ?? geminiTTS;
+    const save = deps.saveRef ?? saveRef;
+    const { pcm, finishReason } = await tts(text, voice, style); // single pass
+    // Gemini just succeeded — the one moment we can capture this peer's voice for
+    // F5 (a ref can't be minted on the F5 path, where Gemini is down). Reuse THIS
+    // output as the ref, keyed to the voice. Best-effort, never affects the audio.
+    await save(personality, pcm, text, voice).catch(() => {});
+    return { pcm, voice, finishReason };
+  },
+};
+
+/** gpt-audio over OpenRouter — cloud second rung, multilingual one pass, style. */
+export const gptAudio = {
+  name: 'gpt-audio',
+  model: GPTAUDIO_MODEL,
+  defaultVoice: DEFAULT_GPTAUDIO_VOICE,
+  capabilities: { style: true, langs: 'any', streaming: false },
+  isFallbackError: (e) =>
+    e instanceof GptAudioQuotaError ||
+    e instanceof GptAudioNoKeyError ||
+    e instanceof GptAudioUnavailableError,
+  async synthesize({ text, voice, style }, deps = {}) {
+    const tts = deps.tts ?? gptAudioTTS;
+    const { pcm } = await tts(text, voice, style);
+    return { pcm, voice };
+  },
+};
+
+/** F5-TTS — live-prosody Russian rung with per-peer voice cloning from a ref. */
+export const f5 = {
+  name: 'f5',
+  model: F5_MODEL,
+  defaultVoice: DEFAULT_F5_VOICE,
+  capabilities: { style: false, langs: ['ru'], streaming: false },
+  isFallbackError: (e) => e instanceof F5UnavailableError,
+  async synthesize({ text, personality, tmpDir }, deps = {}) {
+    const tts = deps.tts ?? f5TTS;
+    const load = deps.loadRef ?? loadRef;
+    const decode = deps.decode ?? decodeToPcmBuffer;
+    // Per-peer voice: load this peer's cached ref → F5 clones their voice. Never
+    // generates here; null when the peer has no ref yet → F5 default voice.
+    const ref = await load(personality);
+    const wav = join(tmpDir, 'f5.wav');
+    await tts(text, 'ru', wav, ref); // F5 reads ruaccent '+' natively
+    const pcm = await decode(wav);
+    return { pcm, voice: ref ? personality : DEFAULT_F5_VOICE, lang: 'ru' };
+  },
+};
+
+/** Supertonic 3 — local, offline floor. One pass in the given language. */
+export const supertonic = {
+  name: 'supertonic',
+  model: SUPERTONIC_MODEL,
+  defaultVoice: DEFAULT_SUPERTONIC_VOICE,
+  capabilities: { style: false, langs: ['ru', 'en', 'na'], streaming: false },
+  // No isFallbackError: the floor. Any error here propagates (real failure).
+  async synthesize({ text, voice, lang, tmpDir }, deps = {}) {
+    const tts = deps.tts ?? supertonicTTS;
+    const decode = deps.decode ?? decodeToPcmBuffer;
+    const wav = join(tmpDir, 'st.wav');
+    await tts(text, lang, wav, voice);
+    const pcm = await decode(wav);
+    return { pcm, voice, lang };
+  },
+};
+
+export const ttsProviders = { gemini, gptAudio, f5, supertonic };
+
+/** The provider for a forced `engine` value, or null for 'auto'. */
+export function ttsProviderByEngine(engine) {
+  if (engine === 'gemini') return gemini;
+  if (engine === 'gpt-audio') return gptAudio;
+  if (engine === 'supertonic') return supertonic;
+  return null;
+}
+
+/**
+ * The declarative `auto` cascade (priority order). Voices are baked per entry;
+ * F5 applies ONLY on the ru route (its English is weak); Supertonic is the floor
+ * and runs in the routed language. Returns entries shaped for runCascade().
+ * @param {{route:'ru'|'en'|'na', gemVoice:string, gaVoice:string, stVoice:string}} a
+ */
+export function buildTtsCascade({ route, gemVoice, gaVoice, stVoice }) {
+  const wrap = (provider, extra) => ({
+    name: provider.name,
+    applicable: extra.applicable,
+    isFallbackError: provider.isFallbackError,
+    run: (ctx) => provider.synthesize({ ...ctx, voice: extra.voice, lang: extra.lang }),
+  });
+  return [
+    wrap(gemini, { voice: gemVoice }),
+    wrap(gptAudio, { voice: gaVoice }),
+    wrap(f5, { lang: 'ru', applicable: () => route === 'ru' }),
+    wrap(supertonic, { voice: stVoice, lang: route }),
+  ];
+}
+
+// ── STT providers ───────────────────────────────────────────────────────────
+// Mirror of the TTS side: uniform contract, declarative cascade. speaches (the
+// OpenAI-compatible HTTP service telegram-runtime already uses) is the primary
+// rung but applies ONLY when an endpoint is configured; mlx-whisper is the local
+// floor. Adding spokenly / Gemini-Flash STT later = one more object here.
+
+/** speaches (faster-whisper, OpenAI /v1/audio/transcriptions) — primary STT. */
+export const speaches = {
+  name: 'speaches',
+  capabilities: { streaming: false, languages: 'any' },
+  isFallbackError: (e) => e instanceof SpeachesUnavailableError,
+  applicable: () => Boolean(sttEndpoint()), // skipped entirely when no endpoint set
+  async transcribe({ audioPath, lang, prompt }, deps = {}) {
+    const stt = deps.stt ?? speachesSTT;
+    const { text } = await stt(audioPath, { lang, prompt });
+    return { text };
+  },
+};
+
+/** mlx_whisper CLI — local, offline STT floor. */
+export const mlxWhisper = {
+  name: 'mlx-whisper',
+  capabilities: { streaming: false, languages: 'any' },
+  // No isFallbackError: the floor. Any error here propagates (real failure).
+  async transcribe({ audioPath, lang, prompt }, deps = {}) {
+    const stt = deps.stt ?? mlxWhisperSTT;
+    const { text } = await stt(audioPath, { lang, prompt });
+    return { text };
+  },
+};
+
+export const sttProviders = { speaches, mlxWhisper };
+
+/** The provider for a forced STT `engine`, or null for 'auto'. */
+export function sttProviderByEngine(engine) {
+  if (engine === 'speaches') return speaches;
+  if (engine === 'mlx-whisper') return mlxWhisper;
+  return null;
+}
+
+/** The declarative STT cascade: speaches (if configured) → mlx-whisper floor. */
+export function buildSttCascade() {
+  const wrap = (provider) => ({
+    name: provider.name,
+    applicable: provider.applicable,
+    isFallbackError: provider.isFallbackError,
+    run: (ctx) => provider.transcribe(ctx),
+  });
+  return [wrap(speaches), wrap(mlxWhisper)];
+}

package/src/ref.mjs

@@ -0,0 +1,157 @@
+/**
+ * Per-peer F5 voice reference — voice-as-identity on the F5 ladder rung (6b).
+ *
+ * F5-TTS clones the voice of a reference sample: POST .../synthesize accepts
+ * {ref_audio_b64, ref_text} and speaks the request in THAT voice. So peer X
+ * sounds like itself on an F5 overflow if we hand F5 a sample of X's voice.
+ *
+ * The catch: a ref of X's voice can only be MINTED while Gemini works (Gemini is
+ * X's primary voice), but F5 runs precisely when Gemini is exhausted. So the ref
+ * is NOT generated on the F5 path. Instead it is REGISTERED opportunistically on
+ * a successful Gemini synthesis (saveRef), reusing that real Gemini output — the
+ * canonical PCM, before ogg encoding — as the sample, with the spoken text as
+ * its transcript. Zero extra Gemini calls. The F5 path only ever loads + sends
+ * (loadRef); if no ref exists yet (peer never spoke via Gemini), F5 uses its
+ * default voice — a self-healing edge case that resolves after X's first synth.
+ *
+ * Mutability: the ref is keyed to the peer's Gemini voice. saveRef stamps the
+ * voice into the meta; when the peer's profile voice later differs, the ref is
+ * STALE and the next well-sized Gemini output refreshes it automatically — so
+ * changing a peer's voice propagates to its F5 voice with no manual step. A
+ * manual reset is just deleting the ref files.
+ *
+ * Cache (per peer X), under $PEER_VOICE_HOME/refs/ (default ~/.iapeer/cache/peer-voice):
+ *   X.wav  — the voice sample (RIFF wav, from the Gemini PCM)
+ *   X.json — { gemini_voice, ref_text, registered_at }
+ */
+import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import { constants as FS } from 'node:fs';
+import { join } from 'node:path';
+import { peerVoiceHome } from './home.mjs';
+import {
+  encodePcmToWav,
+  SAMPLE_RATE,
+  CHANNELS,
+  BYTES_PER_SAMPLE,
+} from './audio.mjs';
+
+const BYTES_PER_SEC = SAMPLE_RATE * CHANNELS * BYTES_PER_SAMPLE; // 48000 B/s
+
+// A good voice clone wants a few seconds of clean speech: too short underdefines
+// the timbre, too long bloats the request and risks artefacts. We register the
+// first suitable Gemini output and skip the rest. Env-tunable.
+const MIN_SEC = Number(process.env.PEER_VOICE_REF_MIN_SEC || '4');
+const MAX_SEC = Number(process.env.PEER_VOICE_REF_MAX_SEC || '15');
+
+// IAP personalities are lowercase slugs; keep the cache filename to that shape so
+// a stray/odd identity can never escape the refs dir.
+const PERSONALITY_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+function refsDir() {
+  return join(peerVoiceHome(), 'refs');
+}
+function refPaths(personality) {
+  const base = join(refsDir(), personality);
+  return { wav: `${base}.wav`, meta: `${base}.json` };
+}
+function validPersonality(personality) {
+  return typeof personality === 'string' && PERSONALITY_RE.test(personality);
+}
+async function exists(p) {
+  try { await access(p, FS.F_OK); return true; } catch { return false; }
+}
+function log(msg) { process.stderr.write(`[peer-voice/ref] ${msg}\n`); }
+
+/** Duration in seconds of a canonical-PCM buffer. */
+export function pcmDurationSec(pcmBuffer) {
+  if (!pcmBuffer || !pcmBuffer.length) return 0;
+  return pcmBuffer.length / BYTES_PER_SEC;
+}
+
+/** Parsed meta for peer X ({ gemini_voice, ref_text, registered_at }), or null. */
+export async function refMeta(personality) {
+  if (!validPersonality(personality)) return null;
+  const { meta } = refPaths(personality);
+  try {
+    const obj = JSON.parse(await readFile(meta, 'utf8'));
+    return obj && typeof obj === 'object' ? obj : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether peer X has a usable cached ref (both the sample and its meta). */
+export async function hasRef(personality) {
+  if (!validPersonality(personality)) return false;
+  const { wav, meta } = refPaths(personality);
+  return (await exists(wav)) && (await exists(meta));
+}
+
+/**
+ * Opportunistically register/refresh peer X's F5 ref from a successful Gemini
+ * synthesis. MUST be called only on the Gemini-success path (never on F5).
+ * Writes nothing — and never touches ffmpeg — when: the personality is odd, the
+ * text is empty, no Gemini voice is given, a CURRENT ref already exists (same
+ * voice), or the audio is outside the [MIN_SEC, MAX_SEC] window (wait for a
+ * better-sized one). When the stored ref was minted for a DIFFERENT Gemini voice
+ * it is treated as stale and refreshed. Best-effort; returns a small result.
+ * @param {string} personality
+ * @param {Buffer} pcmBuffer   canonical PCM (s16le 24 kHz mono), BEFORE ogg encode
+ * @param {string} text        the text Gemini spoke — becomes ref_text (transcript)
+ * @param {string} geminiVoice the peer's Gemini voice this sample was spoken in
+ * @returns {Promise<{saved: boolean, refreshed?: boolean, reason?: string, seconds?: number}>}
+ */
+export async function saveRef(personality, pcmBuffer, text, geminiVoice) {
+  if (!validPersonality(personality)) return { saved: false, reason: 'bad-personality' };
+  if (!text || !String(text).trim()) return { saved: false, reason: 'empty-text' };
+  if (!geminiVoice || !String(geminiVoice).trim()) return { saved: false, reason: 'no-voice' };
+
+  // A ref minted for the SAME voice is current — keep it (registered once per
+  // (peer, voice)). A different voice means the peer's voice changed → stale.
+  const meta = await refMeta(personality);
+  const stale = meta && meta.gemini_voice !== geminiVoice;
+  if (meta && !stale) return { saved: false, reason: 'exists-current' };
+
+  const seconds = pcmDurationSec(pcmBuffer);
+  if (seconds < MIN_SEC || seconds > MAX_SEC) {
+    return { saved: false, reason: 'duration-out-of-window', seconds };
+  }
+
+  const { wav, meta: metaPath } = refPaths(personality);
+  try {
+    await mkdir(refsDir(), { recursive: true });
+    await encodePcmToWav(pcmBuffer, wav);
+    await writeFile(metaPath, JSON.stringify({
+      gemini_voice: geminiVoice,
+      ref_text: String(text),
+      registered_at: new Date().toISOString(),
+    }, null, 2), 'utf8');
+    log(`${stale ? 'refreshed' : 'registered'} ref for "${personality}" `
+      + `(voice ${geminiVoice}, ${seconds.toFixed(1)}s).`);
+    return { saved: true, refreshed: !!stale, seconds };
+  } catch (e) {
+    log(`saveRef failed for "${personality}" (${e.message}); will retry on a later synthesis.`);
+    return { saved: false, reason: 'write-error' };
+  }
+}
+
+/**
+ * Load peer X's cached F5 ref, or null when there is none / it is unreadable.
+ * Never generates — generation is saveRef's job, on the Gemini path.
+ * @param {string} personality
+ * @returns {Promise<{personality: string, audioB64: string, text: string}|null>}
+ */
+export async function loadRef(personality) {
+  if (!(await hasRef(personality))) return null;
+  const { wav } = refPaths(personality);
+  try {
+    const meta = await refMeta(personality);
+    const text = meta && meta.ref_text ? String(meta.ref_text).trim() : '';
+    const audioB64 = (await readFile(wav)).toString('base64');
+    if (!audioB64 || !text) return null;
+    return { personality, audioB64, text };
+  } catch (e) {
+    log(`loadRef failed for "${personality}" (${e.message}); using default voice.`);
+    return null;
+  }
+}

package/src/router.mjs

@@ -0,0 +1,91 @@
+/**
+ * Declarative provider router — the formalized engine cascade.
+ *
+ * Before this, voice.mjs hard-coded the fallback ladder as nested try/catch.
+ * The router turns that into data: an ordered list of entries, each with an
+ * `applicable` guard and an `isFallbackError` predicate. The cascade runs them
+ * in order, advancing to the next entry ONLY on a known "can't-serve" error;
+ * any other error propagates so real bugs surface instead of being masked.
+ *
+ * Idea lineage (see the voice-gateway research): a declarative table with
+ * priority + fallback + cooldown (litellm Router). Cooldown is implemented but
+ * INERT by default (cooldownSec = 0) — Phase 1 is a behavior-preserving refactor;
+ * flipping cooldown on is a later, deliberate config change.
+ *
+ * Modality-agnostic: it runs TTS and STT cascades alike. An entry is:
+ *   {
+ *     name: string,                       // 'gemini' | 'speaches' | ...
+ *     applicable?: (ctx) => boolean,      // skip this entry when false (e.g. F5 only for ru)
+ *     isFallbackError?: (err) => boolean, // true → advance the cascade; false/absent → propagate
+ *     run: (ctx) => Promise<object>,      // do the work (synthesize / transcribe / …)
+ *   }
+ *
+ * Returns the successful entry's result, augmented with:
+ *   - name:         the winning entry's name
+ *   - fallbackFrom: 'gemini:GeminiQuotaError→gptaudio:GptAudioNoKeyError' when the
+ *                   cascade fell through failures first, or undefined if the first
+ *                   applicable entry succeeded.
+ */
+
+/**
+ * @param {Array} entries  ordered cascade entries (highest priority first)
+ * @param {object} ctx     synthesis context passed to each entry's synthesize/applicable
+ * @param {object} [opts]
+ * @param {number} [opts.cooldownSec=0]        seconds a failed entry is skipped (0 = inert)
+ * @param {Map}    [opts.cooldownStore]        name → epoch-ms-until-usable (persist across calls to make cooldown stick)
+ * @param {() => number} [opts.now]            clock (injectable for tests)
+ * @param {(name: string, err: Error) => void} [opts.onAdvance]  notified each time the cascade falls through an entry
+ * @returns {Promise<object>} the winning result + { name, fallbackFrom }
+ */
+export async function runCascade(entries, ctx, opts = {}) {
+  const {
+    cooldownSec = 0,
+    cooldownStore = new Map(),
+    now = () => Date.now(),
+    onAdvance,
+  } = opts;
+
+  const trail = [];
+  let lastErr;
+  let skippedForCooldown = false;
+
+  for (const entry of entries) {
+    if (entry.applicable && !entry.applicable(ctx)) continue;
+
+    if (cooldownSec > 0) {
+      const until = cooldownStore.get(entry.name);
+      if (until && until > now()) {
+        skippedForCooldown = true;
+        continue;
+      }
+    }
+
+    try {
+      const result = await entry.run(ctx);
+      return {
+        ...result,
+        name: entry.name,
+        fallbackFrom: trail.length ? trail.join('→') : undefined,
+      };
+    } catch (err) {
+      // Only KNOWN can't-serve errors advance the cascade. Anything else is a
+      // real failure and must surface — never silently swallowed by a fallback.
+      if (entry.isFallbackError && entry.isFallbackError(err)) {
+        trail.push(`${entry.name}:${err.name}`);
+        if (cooldownSec > 0) cooldownStore.set(entry.name, now() + cooldownSec * 1000);
+        if (onAdvance) onAdvance(entry.name, err);
+        lastErr = err;
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  // No applicable entry produced audio.
+  if (lastErr) throw lastErr;
+  throw new Error(
+    skippedForCooldown
+      ? 'voice router: every applicable provider is in cooldown'
+      : 'voice router: no applicable provider for this request',
+  );
+}