@agfpd/voice-connect 0.1.11

package/src/voice.mjs

@@ -0,0 +1,201 @@
+/**
+ * voice_create — TTS routing & synthesis.
+ *
+ * Contract (per Artur, 2026-06-01): voice_create(text, voice?). Plain text is
+ * ALWAYS a single generation pass — no cutting, no joining, no artificial
+ * pauses — on every engine. Minimal load on the agent: give text, get an ogg.
+ *
+ * Engine routing is a four-rung fallback ladder, now expressed declaratively:
+ * the provider table lives in providers.mjs and the cascade is run by router.mjs.
+ *   - Gemini 3.1 Flash TTS primary — direct Google API, one pass (ru+en).
+ *   - gpt-audio second (OpenRouter) — cloud-quality fallback before the local
+ *     rungs; multilingual one pass, tried for ALL languages.
+ *   - F5-TTS third — LIVE-prosody Russian rung, per-peer voice from a cached ref.
+ *   - Supertonic 3 local floor — offline, one pass in the routed language.
+ *
+ * A `style` directive (HOW to speak) rides on the cloud rungs (Gemini, gpt-audio)
+ * and is ignored by the local rungs. Each rung falls through ONLY on its known
+ * engine-failure classes; other errors propagate so real bugs surface.
+ *
+ * The `||` change-of-language marker is a LATER phase; Phase 1 flattens it away
+ * so it is never read aloud. The tool only PRODUCES the file — delivery
+ * (send_to_peer attachments) is the caller's job.
+ */
+import { mkdtemp, rm, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { classifyLangMode, supertonicLang } from './langsplit.mjs';
+import { encodePcmToOgg, probe } from './audio.mjs';
+import { callerPersonality, resolveVoice } from './profile.mjs';
+import { voiceMap as configVoiceMap } from './config.mjs';
+import { peerVoiceHome } from './home.mjs';
+import { logSynthesis } from './synthlog.mjs';
+import { runCascade } from './router.mjs';
+import { ttsProviders, ttsProviderByEngine, buildTtsCascade } from './providers.mjs';
+
+function defaultOutPath() {
+  const stamp = `${Date.now()}-${randomBytes(4).toString('hex')}`;
+  return join(peerVoiceHome(), 'out', `voice-${stamp}.ogg`);
+}
+
+/** Phase 1: drop the reserved `||` marker so it is not spoken; collapse space. */
+function flattenText(text) {
+  if (typeof text !== 'string') return '';
+  return text.replace(/\|\|/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+/** Caller-supplied lang, normalized to a routing tag or undefined. */
+function normalizeLang(lang) {
+  return ['ru', 'en', 'na'].includes(lang) ? lang : undefined;
+}
+
+/**
+ * Which fallback engine/mode to use when the cloud rungs are down. Returns:
+ *   'ru' → F5 (Russian accent-tune; Supertonic-ru is the floor if F5 is down)
+ *   'en' → Supertonic --lang en
+ *   'na' → Supertonic --lang na (native multilingual, one pass)
+ * An explicit caller `lang` LEADS; otherwise the share-based autodetect
+ * (classifyLangMode); 'mixed' there maps to 'na'.
+ * @param {string} text
+ * @param {'ru'|'en'|'na'|undefined} langOpt already normalized
+ * @returns {'ru'|'en'|'na'}
+ */
+function fallbackRoute(text, langOpt) {
+  if (langOpt) return langOpt;
+  const mode = classifyLangMode(text);
+  return mode === 'mixed' ? 'na' : mode;
+}
+
+/**
+ * Create a voice file from text.
+ *
+ * @param {object} opts
+ * @param {string}  opts.text         text to speak (mixed ru+en is fine)
+ * @param {string}  [opts.voice]      voice for the call's PRIMARY engine (default Aoede on Gemini)
+ * @param {'auto'|'gemini'|'gpt-audio'|'supertonic'} [opts.engine] default 'auto'
+ * @param {'ru'|'en'|'na'} [opts.lang] caller-declared language for the F5/Supertonic rungs
+ * @param {string}  [opts.style]      delivery directive for the cloud rungs
+ * @param {string}  [opts.out_path]   output .ogg path
+ * @returns {Promise<{path,engine,voice,lang?,probe,fallback_from?}>}
+ */
+export async function createVoice(opts = {}) {
+  const engine = ['gemini', 'gpt-audio', 'supertonic', 'auto'].includes(opts.engine) ? opts.engine : 'auto';
+  const langOpt = normalizeLang(opts.lang);
+  const style = typeof opts.style === 'string' && opts.style.trim() ? opts.style.trim() : undefined;
+
+  // Voice resolution: explicit override → caller's interfaces.voice[<model>] →
+  // built-in default. The override is a single voice in the namespace of the
+  // call's PRIMARY engine, so it applies ONLY there — never leaking across a
+  // fallback (a Gemini voice name is invalid for Supertonic, etc.).
+  const override = opts.voice;
+  const personality = callerPersonality(); // whose voice — for the F5 per-peer ref (env → cwd profile)
+  const voiceMap = configVoiceMap(); // mode-aware: iapeer peer-profile → autonomous config file
+  const gemVoice = resolveVoice({
+    modelName: ttsProviders.gemini.model,
+    def: ttsProviders.gemini.defaultVoice,
+    applyOverride: engine === 'auto' || engine === 'gemini',
+    override,
+    voiceMap,
+  }).voice;
+  const gaVoice = resolveVoice({
+    modelName: ttsProviders.gptAudio.model,
+    def: ttsProviders.gptAudio.defaultVoice,
+    applyOverride: engine === 'gpt-audio',
+    override,
+    voiceMap,
+  }).voice;
+  const stVoice = resolveVoice({
+    modelName: ttsProviders.supertonic.model,
+    def: ttsProviders.supertonic.defaultVoice,
+    applyOverride: engine === 'supertonic',
+    override,
+    voiceMap,
+  }).voice;
+
+  const text = flattenText(opts.text);
+  if (!text) {
+    throw new Error('voice_create: `text` is required and must be non-empty.');
+  }
+
+  const outPath = opts.out_path || defaultOutPath();
+  await mkdir(dirname(outPath), { recursive: true });
+  const tmp = await mkdtemp(join(tmpdir(), 'peer-voice-'));
+
+  let usedEngine;
+  let usedVoice;
+  let usedLang;
+  let usedFinishReason; // Gemini-only: how the (final, non-fallback) pass stopped
+  let fallbackFrom;
+  try {
+    const ctx = { text, style, personality, tmpDir: tmp };
+
+    let result;
+    if (engine === 'auto') {
+      // Cloud-quality first (Gemini → gpt-audio), then the language-routed local
+      // rungs (ru → F5 → Supertonic-ru; en/na → Supertonic). An explicit caller
+      // `lang` leads; otherwise the letter-share autodetect.
+      const route = fallbackRoute(text, langOpt); // 'ru' | 'en' | 'na'
+      result = await runCascade(buildTtsCascade({ route, gemVoice, gaVoice, stVoice }), ctx, {
+        onAdvance: (name, err) =>
+          process.stderr.write(`[peer-voice] ${name} unavailable (${err.message}); advancing cascade.\n`),
+      });
+    } else {
+      // Forced single engine — no cascade; its failure propagates to the caller.
+      const provider = ttsProviderByEngine(engine);
+      const voice = engine === 'gemini' ? gemVoice : engine === 'gpt-audio' ? gaVoice : stVoice;
+      // Forced Supertonic honors an explicit lang, else picks ru/en/na by share.
+      const lang = engine === 'supertonic' ? (langOpt ?? supertonicLang(text)) : undefined;
+      result = { ...(await provider.synthesize({ ...ctx, voice, lang })), name: provider.name };
+    }
+
+    usedEngine = result.name;
+    usedVoice = result.voice;
+    usedLang = result.lang;
+    usedFinishReason = result.finishReason;
+    fallbackFrom = result.fallbackFrom;
+
+    await encodePcmToOgg(result.pcm, outPath);
+    const info = await probe(outPath);
+
+    // Structured trace of THIS synthesis — findable post-hoc by output path.
+    await logSynthesis({
+      ok: true,
+      engine: usedEngine,
+      chars: text.length,
+      voice: usedVoice,
+      lang: usedLang ?? null,
+      style: style ?? null,
+      duration: info.duration ?? null,
+      finishReason: usedFinishReason ?? null,
+      fallback_from: fallbackFrom ?? null,
+      path: outPath,
+    });
+
+    return {
+      path: outPath,
+      engine: usedEngine,
+      voice: usedVoice,
+      ...(usedLang ? { lang: usedLang } : {}),
+      probe: info,
+      ...(fallbackFrom ? { fallback_from: fallbackFrom } : {}),
+    };
+  } catch (err) {
+    // Failures leave a trace too — a silent error was half of the original
+    // diagnosis gap. Log what is known, then propagate unchanged.
+    await logSynthesis({
+      ok: false,
+      engine: usedEngine ?? null,
+      chars: text.length,
+      voice: usedVoice ?? null,
+      lang: usedLang ?? null,
+      style: style ?? null,
+      finishReason: usedFinishReason ?? null,
+      fallback_from: fallbackFrom ?? null,
+      error: err instanceof Error ? err.message : String(err),
+    });
+    throw err;
+  } finally {
+    await rm(tmp, { recursive: true, force: true }).catch(() => {});
+  }
+}

package/src/worker.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Detached background worker for async voice jobs (Phase 7, variant B).
+ *
+ * Spawned by jobs.mjs (detached + unref) with one argument: the job file path.
+ * It runs the normal synthesis pipeline OUT of the MCP request, then IAP-
+ * notifies the calling peer:
+ *   - done:   "voice job <id> done path=<path> note=<note>"
+ *   - failed: "voice job <id> failed reason=<...>"
+ * The agent receives that IAP message and delivers the ogg itself
+ * (send_to_peer(<from note>, attachments=[path])).
+ *
+ * Notification goes through the IAP CLI (`iapeer send <personality> --message …`),
+ * resolved from PATH or PEER_VOICE_IAP_BIN — same posture as ffmpeg. The worker
+ * also writes <job>.result.json so completion is observable without the IAP.
+ */
+import { readFile, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createVoice } from './voice.mjs';
+
+const pexecFile = promisify(execFile);
+const IAP_BIN = process.env.PEER_VOICE_IAP_BIN || 'iapeer';
+
+function log(msg) {
+  process.stdout.write(`[peer-voice/worker] ${new Date().toISOString()} ${msg}\n`);
+}
+
+/**
+ * Where to run `iapeer` from. The worker lives inside the CALLING agent's context,
+ * but an IAP message TO that caller must come FROM a different identity — iapeer
+ * refuses send-to-self and ties the sender to the cwd's .iapeer profile. So we
+ * notify AS peer-voice: run iapeer from a dir whose profile is peer-voice (the
+ * package root in dev; PEER_VOICE_NOTIFIER_CWD in deployments where the package
+ * has no profile of its own).
+ */
+function notifierCwd() {
+  return process.env.PEER_VOICE_NOTIFIER_CWD
+    || fileURLToPath(new URL('..', import.meta.url)); // package root (one up from src/)
+}
+
+/** Notify the calling peer over IAP, sent AS peer-voice (not the caller — that
+ *  would be a self-send). Best-effort: a failed send is logged, not thrown. */
+async function notify(personality, message) {
+  if (!personality) {
+    log(`no personality on job — cannot IAP-notify; message was: ${message}`);
+    return;
+  }
+  const cwd = notifierCwd();
+  // iapeer reads the sender from cwd's .iapeer profile and rejects an inherited
+  // identity that disagrees with it (it checks PEER_IDENTITY == PEER_RUNTIME +
+  // "-" + PEER_PERSONALITY against the profile). In production the worker carries
+  // the CALLER's identity vars (e.g. claude-natalya), which would clash with the
+  // peer-voice notifier profile — so strip all three and let iapeer derive the
+  // sender purely from the notifier cwd (→ peer-voice), TO the caller.
+  const env = { ...process.env };
+  delete env.PEER_PERSONALITY;
+  delete env.PEER_IDENTITY;
+  delete env.PEER_RUNTIME;
+  log(`${IAP_BIN} send ${personality} --message ${JSON.stringify(message)} (from cwd ${cwd})`);
+  try {
+    const { stdout, stderr } = await pexecFile(
+      IAP_BIN, ['send', personality, '--message', message, '--topic', 'voice-job'],
+      { cwd, env },
+    );
+    log(`${IAP_BIN} send ok: ${String(stdout || stderr || '').trim().slice(0, 200)}`);
+  } catch (e) {
+    log(`${IAP_BIN} send FAILED: ${e.message}`);
+  }
+}
+
+export async function runJob(jobFile) {
+  const job = JSON.parse(await readFile(jobFile, 'utf8'));
+  // The per-peer F5 ref keys off PEER_PERSONALITY — carry the caller's identity
+  // into this detached process so an overflow still speaks in their voice.
+  if (job.personality) process.env.PEER_PERSONALITY = job.personality;
+  const resultFile = jobFile.replace(/\.json$/, '.result.json');
+  const noteSuffix = job.note ? ` note=${job.note}` : '';
+
+  try {
+    log(`job ${job.job_id} start (chars=${(job.text || '').length}, engine=${job.engine})`);
+    const r = await createVoice({
+      text: job.text,
+      voice: job.voice ?? undefined,
+      engine: job.engine,
+      lang: job.lang ?? undefined,
+      style: job.style ?? undefined,
+      out_path: job.out_path ?? undefined,
+    });
+    log(`job ${job.job_id} synthesized engine=${r.engine} path=${r.path}`);
+    await notify(job.personality, `voice job ${job.job_id} done path=${r.path}${noteSuffix}`);
+    await writeFile(resultFile, JSON.stringify({
+      ...r, job_id: job.job_id, status: 'done', note: job.note ?? null,
+      finished_at: new Date().toISOString(),
+    }, null, 2), 'utf8').catch(() => {});
+  } catch (e) {
+    const reason = e && e.message ? e.message : String(e);
+    log(`job ${job.job_id} FAILED: ${reason}`);
+    await notify(job.personality, `voice job ${job.job_id} failed reason=${reason}`);
+    await writeFile(resultFile, JSON.stringify({
+      job_id: job.job_id, status: 'failed', reason, note: job.note ?? null,
+      finished_at: new Date().toISOString(),
+    }, null, 2), 'utf8').catch(() => {});
+    process.exitCode = 1;
+  }
+}
+
+// Run when invoked directly (the detached spawn); importable without side effects for tests.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const jobFile = process.argv[2];
+  if (!jobFile) {
+    process.stderr.write('peer-voice worker: missing job file argument\n');
+    process.exit(2);
+  }
+  runJob(jobFile).catch(err => {
+    process.stderr.write(`peer-voice worker fatal: ${err && err.stack ? err.stack : err}\n`);
+    process.exit(1);
+  });
+}