@agfpd/voice-connect 0.1.11

package/src/engines/supertonic.mjs

@@ -0,0 +1,177 @@
+/**
+ * Fallback engine — Supertonic 3, local & offline.
+ *
+ * Triggered when Gemini hits its quota (or no key is configured). The caller
+ * passes an explicit --lang: 'ru'/'en' for a dominant single language, or 'na'
+ * (supertonic-3's native multilingual mode) for a balanced ru+en blend — 'na'
+ * reads both in ONE pass with no seams, so mixed text is NOT split by script.
+ * Prosody is flat (66M model — no natural pauses/intonation), but the audio is
+ * clean and it is free/offline, which is exactly what a fallback needs.
+ *
+ * Plug-and-play (§1): the venv and model are provisioned lazily and
+ * idempotently on first fallback use — no manual install step. Resolution
+ * order for the CLI:
+ *   1. PEER_VOICE_SUPERTONIC_BIN (explicit override)
+ *   2. managed venv at $PEER_VOICE_HOME/supertonic-venv  (default ~/.iapeer/cache/peer-voice)
+ *   3. `supertonic` already on PATH
+ *   4. create the managed venv (python3 -m venv) + pip install supertonic
+ * The model (~/.cache/supertonic3) is fetched via `supertonic download` if absent.
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { access, mkdir, readdir } from 'node:fs/promises';
+import { constants as FS } from 'node:fs';
+import { mapStressToUnicode } from '../stress.mjs';
+import { accentPlus } from '../ruaccent.mjs';
+import { hasCyrillic } from '../langsplit.mjs';
+import { peerVoiceHome } from '../home.mjs';
+
+const pexecFile = promisify(execFile);
+
+/** Full model name — the key under interfaces.voice for the Supertonic voice. */
+export const SUPERTONIC_MODEL = 'supertonic-3';
+export const DEFAULT_SUPERTONIC_VOICE = process.env.PEER_VOICE_SUPERTONIC_VOICE || 'F3';
+// 12 = Supertonic's documented quality ceiling (range 5–12; above it plateaus —
+// the 16/32/64 differences Artur heard were generation nondeterminism, not
+// quality). Override via env.
+const STEPS = process.env.PEER_VOICE_SUPERTONIC_STEPS || '12';
+// Supertonic's own default --speed is 1.05 (slightly rushed). 0.9 reads at a
+// calmer, more natural pace — Artur's call on the palette. Override via env.
+const SPEED = process.env.PEER_VOICE_SUPERTONIC_SPEED || '0.9';
+
+function managedVenvBin() {
+  return join(peerVoiceHome(), 'supertonic-venv', 'bin', 'supertonic');
+}
+function modelDir() {
+  return process.env.SUPERTONIC_MODEL_DIR || join(homedir(), '.cache', 'supertonic3');
+}
+
+async function exists(p) {
+  try { await access(p, FS.X_OK); return true; } catch { return false; }
+}
+
+/**
+ * The model is "present" iff at least one *.onnx weight file exists under the
+ * model dir. A bare/partial dir (e.g. a download interrupted mid-flight) does
+ * NOT count — checking the dir alone would wrongly skip a needed download, and
+ * `supertonic download` is destructive (it rebuilds the target dir).
+ */
+async function modelPresent(dir) {
+  let entries;
+  try { entries = await readdir(dir, { withFileTypes: true }); } catch { return false; }
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (await modelPresent(full)) return true;
+    } else if (e.name.endsWith('.onnx')) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function log(msg) {
+  process.stderr.write(`[peer-voice/supertonic] ${msg}\n`);
+}
+
+async function run(bin, args, opts = {}) {
+  return pexecFile(bin, args, { maxBuffer: 64 * 1024 * 1024, ...opts });
+}
+
+let cachedBin = null;
+
+/** Resolve (and if needed provision) the supertonic CLI. Idempotent. */
+export async function ensureSupertonic() {
+  if (cachedBin) return cachedBin;
+
+  // 1. explicit override
+  if (process.env.PEER_VOICE_SUPERTONIC_BIN) {
+    cachedBin = process.env.PEER_VOICE_SUPERTONIC_BIN;
+    return cachedBin;
+  }
+  // 2. managed venv
+  const managed = managedVenvBin();
+  if (await exists(managed)) {
+    cachedBin = managed;
+    await ensureModel(cachedBin);
+    return cachedBin;
+  }
+  // 3. already on PATH
+  try {
+    await run('supertonic', ['--version']);
+    cachedBin = 'supertonic';
+    await ensureModel(cachedBin);
+    return cachedBin;
+  } catch { /* not on PATH — provision below */ }
+
+  // 4. create managed venv + install
+  const venvDir = join(peerVoiceHome(), 'supertonic-venv');
+  log(`provisioning venv at ${venvDir} (one-time)…`);
+  await mkdir(peerVoiceHome(), { recursive: true });
+  const py = process.env.PEER_VOICE_PYTHON || 'python3';
+  await run(py, ['-m', 'venv', venvDir]);
+  const pip = join(venvDir, 'bin', 'pip');
+  log('pip install supertonic + ruaccent (downloading onnxruntime — may take a few minutes)…');
+  await run(pip, ['install', '--quiet', '--upgrade', 'pip']);
+  // ruaccent ships alongside supertonic (Russian stress, see accentRussian).
+  // transformers + onnxruntime, no torch — light. Idempotent on reruns.
+  await run(pip, ['install', '--quiet', 'supertonic', 'ruaccent']);
+  cachedBin = managed;
+  await ensureModel(cachedBin);
+  return cachedBin;
+}
+
+/** Fetch the model from Hugging Face if absent. Idempotent (skips if a *.onnx
+ *  weight already exists under the model dir). */
+async function ensureModel(bin) {
+  if (await modelPresent(modelDir())) return;
+  log('model not found — running `supertonic download` (one-time, from Hugging Face)…');
+  const args = ['download'];
+  if (process.env.SUPERTONIC_MODEL_DIR) args.push('--out', process.env.SUPERTONIC_MODEL_DIR);
+  await run(bin, args);
+}
+
+// --- Russian stress via ruaccent ------------------------------------------
+//
+// Supertonic's weak Russian stress (синтЕза/сИнтеза, omographs замок/замок) is
+// the main complaint. ruaccent marks stress with '+' before the stressed vowel
+// (shared module ruaccent.mjs); Supertonic mis-reads the raw '+' as a sound, so
+// stress.mjs maps '+vowel' -> 'vowel'+U+0301, which Supertonic honors. Gemini
+// stresses Russian correctly on its own, so this is the Supertonic branch ONLY.
+// Best-effort: any failure falls back to the original text — stress is an
+// enhancement, never a hard dependency for synthesis.
+
+/** Add Russian stress (U+0301) to text, or return it unchanged on any failure.
+ *  Hint ruaccent at the python beside our resolved CLI (managed venv, or an
+ *  override pointing at a venv); ruaccent.mjs falls back to the managed venv. */
+async function accentRussian(text) {
+  const hint = cachedBin ? join(dirname(cachedBin), 'python') : undefined;
+  return mapStressToUnicode(await accentPlus(text, hint));
+}
+
+/**
+ * Synthesize one text to a wav file.
+ * @param {string} text
+ * @param {'ru'|'en'|'na'|string} lang  'na' = native multilingual (balanced ru+en)
+ * @param {string} wavPath
+ * @param {string} [voice]
+ * @returns {Promise<string>} wavPath
+ */
+export async function supertonicTTS(text, lang, wavPath, voice = DEFAULT_SUPERTONIC_VOICE) {
+  const bin = await ensureSupertonic();
+  // Place Russian stress whenever the text has Cyrillic — for 'ru' AND for the
+  // multilingual 'na' blend, whose Russian part needs it just as much. ruaccent
+  // marks only Russian vowels (English passes through untouched), so this is
+  // safe on mixed text. Pure-'en' (no Cyrillic) skips it. Best-effort.
+  const speakText = hasCyrillic(text) ? await accentRussian(text) : text;
+  // --model pinned explicitly: the package default could change in a future
+  // release; supertonic-3 is the model we provision and key interfaces.voice by.
+  await run(bin, [
+    'tts', speakText, '-o', wavPath,
+    '--model', SUPERTONIC_MODEL,
+    '--lang', lang, '--voice', voice, '--steps', STEPS, '--speed', SPEED,
+  ]);
+  return wavPath;
+}

package/src/home.mjs

@@ -0,0 +1,15 @@
+/**
+ * Plugin data home.
+ *
+ * Team convention: agent/plugin data lives under ~/.iapeer/cache/<plugin>/
+ * (alongside mergemind, spawned-peer, persistent-peer). peer-voice keeps its
+ * managed Supertonic venv, ref cache, and output files there too — one place,
+ * consistent with the rest of the stand. Override the whole root via the
+ * PEER_VOICE_HOME env var.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function peerVoiceHome() {
+  return process.env.PEER_VOICE_HOME || join(homedir(), '.iapeer', 'cache', 'peer-voice');
+}

package/src/http.mjs

@@ -0,0 +1,252 @@
+/**
+ * voice-connect HTTP facade — an OpenAI-compatible local audio service over the
+ * SAME core as the MCP server (voice.mjs createVoice + stt.mjs transcribe via
+ * router/providers). This is the path runtimes (telegram-runtime, voicetalk)
+ * take directly, without MCP:
+ *
+ *   POST /v1/audio/speech          — TTS. JSON in, Ogg/Opus bytes out.
+ *   POST /v1/audio/transcriptions  — STT. multipart/form-data in, text/JSON out.
+ *   GET  /health                   — liveness for launchd / monitoring.
+ *
+ * The contracts mirror OpenAI's audio API so an off-the-shelf client (or the
+ * speaches/Kokoro shape telegram-runtime already drives) can point at this
+ * facade unchanged. The endpoints reuse the core verbatim — no synthesis or
+ * routing logic is duplicated here; this file is just HTTP wiring, the twin of
+ * server.mjs's MCP wiring.
+ *
+ * HTTP is synchronous request/response: a runtime holds the connection and
+ * wants bytes back. So /v1/audio/speech ALWAYS synthesizes inline (no async
+ * job / IAP-notify path — that belongs to the MCP tool, where an agent would
+ * otherwise block). Long input simply takes longer to return.
+ *
+ * Pure Node ESM, zero new deps: multipart is parsed by building a web `Request`
+ * from the raw body and calling `.formData()` (undici, built in since Node 18),
+ * not a hand-rolled boundary parser.
+ */
+import { createServer as nodeCreateServer } from 'node:http';
+import { readFile, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { createVoice } from './voice.mjs';
+import { transcribe as transcribeAudio } from './stt.mjs';
+import { readVersion } from './server.mjs';
+
+/** Upload cap — generous for a voice message, bounded so a bad request can't OOM us. */
+const MAX_BODY = 64 * 1024 * 1024;
+
+export const DEFAULT_HTTP_PORT = 8127;
+
+/** Listening port: env PEER_VOICE_HTTP_PORT, else the default. */
+export function httpPort() {
+  const p = parseInt(process.env.PEER_VOICE_HTTP_PORT || '', 10);
+  return Number.isInteger(p) && p > 0 ? p : DEFAULT_HTTP_PORT;
+}
+
+/** Bind host: env PEER_VOICE_HTTP_HOST, else loopback (local-only by default). */
+export function httpHost() {
+  return (process.env.PEER_VOICE_HTTP_HOST || '127.0.0.1').trim() || '127.0.0.1';
+}
+
+const TTS_ENGINES = ['gemini', 'gpt-audio', 'supertonic', 'auto'];
+const STT_ENGINES = ['speaches', 'mlx-whisper', 'auto'];
+const LANGS = ['ru', 'en', 'na'];
+
+/** Read the full request body into a Buffer, enforcing the size cap (→ 413). */
+async function readBody(req, limit = MAX_BODY) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > limit) {
+      const err = new Error('request body too large');
+      err.statusCode = 413;
+      throw err;
+    }
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+
+function sendJson(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' });
+  res.end(body);
+}
+
+/** OpenAI-shaped error envelope: { error: { message, type } }. */
+function sendError(res, status, message, type = 'invalid_request_error') {
+  sendJson(res, status, { error: { message, type } });
+}
+
+function str(v) {
+  return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+}
+
+/**
+ * POST /v1/audio/speech — text → Ogg/Opus bytes.
+ *
+ * Request JSON (OpenAI `audio/speech` plus extensions):
+ *   input   (or text)  required — the text to speak
+ *   voice              optional — voice override for the primary engine
+ *   model              optional — if it names one of our engines, selects it
+ *   engine             optional — explicit engine (wins over model); default auto
+ *   lang               optional — ru|en|na hint for the fallback rungs
+ *   style              optional — delivery directive for the cloud rungs
+ *   response_format    advisory — we always emit Ogg/Opus (see header X-Voice-Format)
+ *
+ * Always synchronous: the response body is the audio. Engine/fallback are
+ * surfaced in X-Voice-* headers for observability.
+ */
+async function handleSpeech(req, res, { voice }) {
+  const raw = await readBody(req);
+  let body;
+  try {
+    body = raw.length ? JSON.parse(raw.toString('utf8')) : {};
+  } catch {
+    return sendError(res, 400, 'invalid JSON body');
+  }
+  const text = str(body.input) ?? str(body.text);
+  if (!text) return sendError(res, 400, '`input` (the text to speak) is required');
+
+  // engine: explicit `engine` leads; else `model` when it names one of ours; else auto.
+  const engine = TTS_ENGINES.includes(body.engine)
+    ? body.engine
+    : TTS_ENGINES.includes(body.model)
+      ? body.model
+      : 'auto';
+  const voiceArg = str(body.voice);
+  const lang = LANGS.includes(body.lang) ? body.lang : undefined;
+  const style = str(body.style);
+
+  // Synthesize to a throwaway temp file, stream its bytes, then delete it —
+  // the runtime gets the audio in the response and needs nothing on disk.
+  const outPath = join(tmpdir(), `peer-voice-http-${Date.now()}-${randomBytes(4).toString('hex')}.ogg`);
+  try {
+    const result = await voice({ text, voice: voiceArg, engine, lang, style, out_path: outPath });
+    const bytes = await readFile(result.path);
+    res.writeHead(200, {
+      'content-type': 'audio/ogg',
+      'content-length': bytes.length,
+      'x-voice-format': 'opus',
+      ...(result.engine ? { 'x-voice-engine': String(result.engine) } : {}),
+      ...(result.voice ? { 'x-voice-voice': String(result.voice) } : {}),
+      ...(result.fallback_from ? { 'x-voice-fallback-from': String(result.fallback_from) } : {}),
+    });
+    res.end(bytes);
+  } finally {
+    await rm(outPath, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * POST /v1/audio/transcriptions — audio file → text.
+ *
+ * Request multipart/form-data (OpenAI `audio/transcriptions` plus extensions):
+ *   file             required — the audio upload (.ogg/.wav/.mp3/…)
+ *   language         optional — ISO-639-1 hint
+ *   prompt           optional — decoder-priming prompt (term spelling/casing)
+ *   engine           optional — speaches|mlx-whisper|auto (default auto)
+ *   response_format  optional — text → plain body; else JSON { text }
+ *
+ * `response_format=text` mirrors what telegram-runtime's speaches client sends
+ * (it reads res.text()), so this facade is a drop-in for that endpoint.
+ */
+async function handleTranscriptions(req, res, { transcribe }) {
+  const ctype = req.headers['content-type'] || '';
+  if (!ctype.includes('multipart/form-data')) {
+    return sendError(res, 400, 'expected multipart/form-data with a `file` field');
+  }
+  const raw = await readBody(req);
+  let form;
+  try {
+    const request = new Request('http://localhost/v1/audio/transcriptions', {
+      method: 'POST',
+      headers: { 'content-type': ctype },
+      body: raw,
+    });
+    form = await request.formData();
+  } catch (err) {
+    return sendError(res, 400, `could not parse multipart body: ${err && err.message ? err.message : err}`);
+  }
+
+  const file = form.get('file');
+  if (!file || typeof file === 'string' || typeof file.arrayBuffer !== 'function') {
+    return sendError(res, 400, '`file` field (the audio upload) is required');
+  }
+  const lang = str(form.get('language'));
+  const prompt = str(form.get('prompt'));
+  const respFormat = str(form.get('response_format')) ?? 'json';
+  const engineRaw = form.get('engine');
+  const engine = STT_ENGINES.includes(engineRaw) ? engineRaw : 'auto';
+
+  // The core transcribe() takes a path, so persist the upload to a temp file,
+  // preserving any extension hint so a whisper backend can sniff the container.
+  const name = typeof file.name === 'string' ? file.name : '';
+  const ext = /\.[a-z0-9]{1,5}$/i.test(name) ? name.slice(name.lastIndexOf('.')) : '.ogg';
+  const tmpPath = join(tmpdir(), `peer-voice-stt-${Date.now()}-${randomBytes(4).toString('hex')}${ext}`);
+  try {
+    await writeFile(tmpPath, Buffer.from(await file.arrayBuffer()));
+    const result = await transcribe({ audioPath: tmpPath, lang, prompt, engine });
+    if (respFormat === 'text') {
+      res.writeHead(200, { 'content-type': 'text/plain; charset=utf-8' });
+      res.end(result.text);
+    } else {
+      sendJson(res, 200, { text: result.text });
+    }
+  } finally {
+    await rm(tmpPath, { force: true }).catch(() => {});
+  }
+}
+
+/**
+ * Build the HTTP server. Seams `voice`/`transcribe` are injectable so tests can
+ * drive real HTTP against a stub core (no network, no ffmpeg). The factory is
+ * pure (no listen); main() owns the side-effecting bind.
+ */
+export function createHttpServer({ voice, transcribe, version } = {}) {
+  const voiceImpl = voice ?? createVoice;
+  const transcribeImpl = transcribe ?? transcribeAudio;
+  const ver = version ?? readVersion();
+
+  return nodeCreateServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, 'http://localhost');
+      const path = url.pathname.replace(/\/+$/, '') || '/';
+
+      if (req.method === 'GET' && (path === '/' || path === '/health' || path === '/healthz')) {
+        return sendJson(res, 200, { status: 'ok', service: 'voice-connect', version: ver });
+      }
+      if (path === '/v1/audio/speech') {
+        if (req.method !== 'POST') return sendError(res, 405, 'method not allowed; use POST');
+        return await handleSpeech(req, res, { voice: voiceImpl });
+      }
+      if (path === '/v1/audio/transcriptions') {
+        if (req.method !== 'POST') return sendError(res, 405, 'method not allowed; use POST');
+        return await handleTranscriptions(req, res, { transcribe: transcribeImpl });
+      }
+      return sendError(res, 404, `unknown route: ${req.method} ${path}`, 'not_found');
+    } catch (err) {
+      const status = err && err.statusCode ? err.statusCode : 500;
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!res.headersSent) sendError(res, status, msg, status === 500 ? 'server_error' : 'invalid_request_error');
+      else res.end();
+    }
+  });
+}
+
+/** Bootstrap: bind and run the always-on facade. Importable without side effects. */
+export async function main() {
+  const server = createHttpServer();
+  const port = httpPort();
+  const host = httpHost();
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, resolve);
+  });
+  process.stderr.write(`voice-connect http: listening on http://${host}:${port} (version ${readVersion()})\n`);
+  for (const sig of ['SIGINT', 'SIGTERM']) {
+    process.on(sig, () => server.close(() => process.exit(0)));
+  }
+  return server;
+}

package/src/jobs.mjs

@@ -0,0 +1,95 @@
+/**
+ * Async voice jobs (Phase 7, variant B — notify-agent).
+ *
+ * Long synthesis (10–20 min of audio) takes minutes; a synchronous tool call
+ * would block the calling agent — and its billing — for that whole time. So
+ * voice_create splits by length:
+ *   - short text (≤ threshold)  → handled synchronously (returns {path,...}).
+ *   - long text  (>  threshold) → dispatched here: a DETACHED worker process
+ *     does the synthesis out-of-band and IAP-notifies the agent on completion,
+ *     while the tool returns {job_id, status:"started"} in <1s.
+ *
+ * The worker (worker.mjs) survives the MCP handler's return (detached + unref,
+ * own session), reads the job file, runs the normal pipeline, and on done/fail
+ * sends the calling peer an IAP message. The agent then delivers the ogg itself.
+ *
+ * Job artifacts live under $PEER_VOICE_HOME/jobs/ (default ~/.iapeer/cache/peer-voice):
+ *   <job_id>.json        — the dispatched job (text, voice, note, personality…)
+ *   <job_id>.log         — the worker's stdout/stderr
+ *   <job_id>.result.json — written by the worker on completion (status, path|reason)
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import { openSync, closeSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { peerVoiceHome } from './home.mjs';
+
+/** Char count above which a request goes async. ~2000 chars ≈ ~1 min of audio.
+ *  Read at call time so it is env-tunable (tests, ops). */
+export function asyncThresholdChars() {
+  return Number(process.env.PEER_VOICE_ASYNC_THRESHOLD_CHARS || '2000');
+}
+
+/** Whether this text should be synthesized asynchronously (too long for sync). */
+export function isLongText(text) {
+  return typeof text === 'string' && text.length > asyncThresholdChars();
+}
+
+export function jobsDir() {
+  return join(peerVoiceHome(), 'jobs');
+}
+
+/** A sortable, collision-resistant job id (time36 + random). */
+export function newJobId() {
+  return `${Date.now().toString(36)}-${randomBytes(4).toString('hex')}`;
+}
+
+/** Persist the job spec so the detached worker can pick it up. Returns its path. */
+export async function writeJobFile(job) {
+  const dir = jobsDir();
+  await mkdir(dir, { recursive: true });
+  const jobFile = join(dir, `${job.job_id}.json`);
+  await writeFile(jobFile, JSON.stringify(job, null, 2), 'utf8');
+  return jobFile;
+}
+
+/**
+ * Dispatch a long synthesis to a detached background worker.
+ * @param {object} opts {text, voice?, engine?, lang?, style?, out_path?, note?, personality?}
+ * @returns {Promise<{job_id: string, status: 'started'}>} returned in <1s
+ */
+export async function dispatchVoiceJob(opts = {}) {
+  const job_id = newJobId();
+  const job = {
+    job_id,
+    text: opts.text,
+    voice: opts.voice ?? null,
+    engine: opts.engine ?? 'auto',
+    lang: opts.lang ?? null,
+    style: opts.style ?? null,
+    out_path: opts.out_path ?? null,
+    note: opts.note ?? null,
+    personality: opts.personality ?? null,
+    created_at: new Date().toISOString(),
+  };
+  const jobFile = await writeJobFile(job);
+
+  // Detached so it outlives this handler's return (and even this MCP server):
+  // own session, unref'd, stdio to a per-job log. The worker reads jobFile.
+  const logFile = join(jobsDir(), `${job_id}.log`);
+  const out = openSync(logFile, 'a');
+  const workerPath = fileURLToPath(new URL('./worker.mjs', import.meta.url));
+  try {
+    const child = spawn(process.execPath, [workerPath, jobFile], {
+      detached: true,
+      stdio: ['ignore', out, out],
+      env: process.env,
+    });
+    child.unref();
+  } finally {
+    closeSync(out); // the child holds its own dup of the fd
+  }
+  return { job_id, status: 'started' };
+}

package/src/langsplit.mjs

@@ -0,0 +1,129 @@
+/**
+ * Language helpers.
+ *
+ * `detectDominantLang` — plain text is ALWAYS one pass, so a monolingual call
+ * needs the single dominant language. Cyrillic vs Latin character count; ru on a
+ * tie or when neither is present (the team default).
+ *
+ * `classifyLangMode` / `supertonicLang` — language-aware fallback-engine routing
+ * (Artur 2026-06-01). The fallback engine (when Gemini is down) is picked by the
+ * text's language mix, not just its dominant script. See classifyLangMode.
+ *
+ * Phase 4 (reserved, not wired into the tool yet): `splitByLang` — when an
+ * explicit `||` change-of-language marker is present, text is cut by the marker
+ * and each chunk synthesized in its own language; the join produces a natural
+ * pause at the seam. Kept here for that phase; Phase 1 flattens `||` away.
+ */
+
+const CYR = /[Ѐ-ӿ]/;
+const LAT = /[A-Za-z]/;
+const CYR_G = /[Ѐ-ӿ]/g;
+const LAT_G = /[A-Za-z]/g;
+
+// A language is "dominant" only when it holds at least this share of the letters
+// (Artur's ~80% guideline). Below it, neither side overwhelms → the text is a
+// genuine blend. A monolingual --lang would mangle the minority script, so a
+// blend goes to Supertonic's native multilingual ('na') pass instead. The same
+// 0.8 cutoff guards the F5 (Russian) branch: F5's Russian is far better, and it
+// reads a ≤20% English minority intelligibly, so ru ≥0.8 is worth F5; below that
+// we don't risk F5's weak English. Env-tunable for live calibration.
+const DOMINANT_SHARE = Number(process.env.PEER_VOICE_DOMINANT_SHARE || '0.8');
+
+/**
+ * Dominant language of the whole text.
+ * @param {string} text
+ * @param {'ru'|'en'} [fallback] used when neither script appears / on a tie
+ * @returns {'ru'|'en'|string}
+ */
+export function detectDominantLang(text, fallback = 'ru') {
+  const cyr = (text.match(CYR_G) || []).length;
+  const lat = (text.match(LAT_G) || []).length;
+  if (cyr === 0 && lat === 0) return fallback;
+  if (cyr === lat) return fallback;
+  return cyr > lat ? 'ru' : 'en';
+}
+
+/**
+ * Three-way language mode for fallback-engine routing (Artur 2026-06-01) — the
+ * DEFAULT used only when the caller does not pass an explicit `lang`:
+ *   'ru'    — Russian holds ≥ DOMINANT_SHARE of the letters (English inserts ok).
+ *   'en'    — English holds ≥ DOMINANT_SHARE (Russian negligible).
+ *   'mixed' — neither overwhelms: a genuine ru+en blend.
+ * The asymmetry the routing wants is encoded by the consumers, not here: 'ru'
+ * → F5 (Russian accent-tune), 'en' → Supertonic --lang en, 'mixed' → Supertonic
+ * --lang na (native multilingual, one pass). A monolingual --lang would mangle
+ * the minority script, which is exactly why a blend uses 'na'.
+ * @param {string} text
+ * @returns {'ru'|'en'|'mixed'}
+ */
+export function classifyLangMode(text) {
+  const s = String(text);
+  const cyr = (s.match(CYR_G) || []).length;
+  const lat = (s.match(LAT_G) || []).length;
+  const total = cyr + lat;
+  if (total === 0) return 'ru';                      // neutral-only → team default
+  const cyrShare = cyr / total;
+  if (cyrShare >= DOMINANT_SHARE) return 'ru';       // Russian overwhelmingly leads
+  if (cyrShare <= 1 - DOMINANT_SHARE) return 'en';   // English overwhelmingly leads
+  return 'mixed';                                    // both substantial → 'na'
+}
+
+/**
+ * Supertonic --lang code for a text under the share heuristic: 'ru' | 'en' |
+ * 'na' (na = supertonic-3's native multilingual mode for a balanced blend).
+ * @param {string} text
+ * @returns {'ru'|'en'|'na'}
+ */
+export function supertonicLang(text) {
+  const mode = classifyLangMode(text);
+  return mode === 'mixed' ? 'na' : mode;
+}
+
+/** True iff the text contains any Cyrillic letter → it wants Russian stress
+ *  (ruaccent), whether the synthesis lang is 'ru' or the multilingual 'na'. */
+export function hasCyrillic(text) {
+  return CYR.test(String(text));
+}
+
+function classify(token) {
+  if (CYR.test(token)) return 'ru';
+  if (LAT.test(token)) return 'en';
+  return null; // neutral: punctuation / digits / spaces / symbols
+}
+
+/**
+ * Phase 4 — split mixed text into single-language runs (Cyrillic→ru, Latin→en).
+ * Neutral tokens glue onto the current run so nothing is lost. Not used by the
+ * Phase 1 tool surface.
+ * @param {string} text
+ * @param {'ru'|'en'} [fallbackLang] language for neutral-only text
+ * @returns {Array<{text: string, lang: 'ru'|'en'}>}
+ */
+export function splitByLang(text, fallbackLang = 'ru') {
+  const tokens = text.match(/\S+|\s+/g) || [];
+  const runs = [];
+  let cur = null;
+  let pendingNeutral = '';
+
+  for (const tok of tokens) {
+    const lang = classify(tok);
+    if (lang === null) {
+      if (cur) cur.text += tok;
+      else pendingNeutral += tok;
+      continue;
+    }
+    if (cur && cur.lang === lang) {
+      cur.text += tok;
+    } else {
+      if (cur) runs.push(cur);
+      cur = { text: pendingNeutral + tok, lang };
+      pendingNeutral = '';
+    }
+  }
+  if (cur) runs.push(cur);
+  else if (pendingNeutral.trim()) runs.push({ text: pendingNeutral, lang: fallbackLang });
+
+  return runs
+    .map(r => ({ text: r.text.trim(), lang: r.lang }))
+    .filter(r => r.text.length > 0);
+}