@goodandready/dsh-tts 0.4.0 → 0.4.2

package/lib/index.js

@@ -11,6 +11,7 @@ import { createModelManager } from './engines/manager.js'
 import { registerHttpRoutes } from './routes.js'
 import { broadcastStream, clearStreamSubscribers } from './stream-hub.js'
 import { writeJson } from './http-util.js'
+import { createProviderBreaker } from './breaker.js'
 import {
   CLOUD_PROVIDERS,
   assertCredentialRef,
@@ -126,11 +127,11 @@ export const Config = z.object({
   approvalText: z
     .string()
     .description('What to say when an approval is asked for. The tool name is appended.')
-    .default('Требуется подтверждение'),
+    .default('Approval required'),
   questionText: z
     .string()
     .description('What to say when the agent asks a question. Empty disables it.')
-    .default('Агент задал вопрос'),
+    .default('Agent asked a question'),
   chime: z
     .string()
     .description('Short sound before an announcement: ding, beep or none.')
@@ -177,6 +178,8 @@ export const Config = z.object({
 let utteranceSeq = 0
 
 export function apply(ctx, config) {
+  const providerBreaker = createProviderBreaker()
+
   let getConfig = () => config
   const live = () => Config(structuredClone(getConfig() ?? {})) ?? config
 
@@ -338,7 +341,7 @@ export function apply(ctx, config) {
         try {
           const retold = await summarizeReply(text.slice(0, 8000), cfg, signal)
           if (retold) cut = speechPhrases(cfg.language).summaryIntro + ' ' + retold
-        } catch (llmDown) { /* тихий откат к обрезке */ }
+        } catch (llmDown) { /* quiet fallback to truncation */ }
       }
       text = cut
     }
@@ -380,10 +383,28 @@ export function apply(ctx, config) {
 
     const synthPromise = (async () => {
       try {
-        const providers = makeProviders(
+        const baseProviders = makeProviders(
           { resolveKey, fetchImpl: fetch, cfg, modelManager },
           { text, lang: cfg.autoDetect ? detectLang(text) : cfg.language, signal, models, voices, role },
         )
+        const providers = {}
+        for (const key of Object.keys(baseProviders)) {
+          const fn = baseProviders[key]
+          providers[key] = async () => {
+            if (providerBreaker.isOpen(key)) {
+              return { ok: false, provider: key, reason: 'circuit open (cooldown)' }
+            }
+            try {
+              const out = await fn()
+              if (out && out.ok) providerBreaker.recordSuccess(key)
+              else providerBreaker.recordFailure(key, out && out.reason)
+              return out
+            } catch (err) {
+              providerBreaker.recordFailure(key, err)
+              throw err
+            }
+          }
+        }
         const out = await runChain(order, providers)
         stats.total++
         const ps = stats.providers[out.provider] || (stats.providers[out.provider] = { n: 0, e: 0, ms: 0 })
@@ -549,6 +570,8 @@ export function apply(ctx, config) {
 
 
   registerHttpRoutes(ctx, {
+    breakerSnapshot: () => providerBreaker.snapshot(),
+
     live,
     modelManager,
     stats,
@@ -560,6 +583,8 @@ export function apply(ctx, config) {
     storeProviderKey,
     clearProviderKey,
     pending,
+    getSettingsApi: () => settingsApi,
+    validateConfig: (obj) => Config(obj),
   })
 
   ctx.effect(() => () => {

package/lib/local.js

@@ -83,15 +83,13 @@ export async function edgeSpeak(text, { bin, voice, timeoutMs }) {
 
 
 /**
- * MiniMax через их консольную утилиту.
+ * MiniMax via their official CLI utility.
  *
- * Прямого HTTP тут намеренно нет: у MiniMax свой протокол с отдельным
- * идентификатором группы и своей формой ответа, а официальная утилита уже
- * умеет и авторизацию, и выбор голоса. Она же хранит вход — плагину не нужно
- * знать ни ключа, ни устройства их API.
+ * There is intentionally no direct HTTP here: MiniMax uses its own protocol with a
+ * separate group id and response shape, while the official CLI already handles auth
+ * and voice selection. It also stores the login — the plugin never sees the key.
  *
- * Утилита ставится отдельно и один раз логинится; без неё провайдер честно
- * отказывает, и цепочка идёт дальше.
+ * The utility is installed separately and logs in once; without it the provider fails honestly and the chain moves on.
  */
 export async function minimaxSpeak(text, { bin, voice, model, timeoutMs }) {
   const dir = await mkdtemp(path.join(os.tmpdir(), 'dsh-tts-minimax-'))

package/lib/providers/constants.js

@@ -0,0 +1,61 @@
+export const PROVIDER_KEYS = [
+  'kokoro', 'f5',
+  'openai', 'elevenlabs', 'google', 'azure', 'groq', 'deepgram', 'openrouter',
+  'siliconflow', 'deepinfra', 'fireworks', 'mimo', 'custom',
+  'edge', 'piper', 'espeak', 'minimax',
+]
+
+// OpenAI-compatible providers share /audio/speech; they differ by base URL,
+// model, and key name. Each URL was probed without a key and returned 401.
+export const OPENAI_COMPATIBLE = {
+  siliconflow: { baseUrl: 'https://api.siliconflow.cn/v1', keyEnv: 'SILICONFLOW_API_KEY' },
+  deepinfra: { baseUrl: 'https://api.deepinfra.com/v1/openai', keyEnv: 'DEEPINFRA_API_KEY' },
+  fireworks: { baseUrl: 'https://api.fireworks.ai/inference/v1', keyEnv: 'FIREWORKS_API_KEY' },
+  // Custom endpoint: base URL and key name come from settings.
+  custom: { baseUrl: '', keyEnv: 'CUSTOM_TTS_API_KEY' },
+}
+
+export const DEFAULT_MODELS = {
+  kokoro: 'hexgrad/Kokoro-82M',
+  f5: 'F5-TTS',
+  mimo: 'mimo-v2.5-tts',
+  minimax: '',
+  siliconflow: 'FunAudioLLM/CosyVoice2-0.5B',
+  deepinfra: 'hexgrad/Kokoro-82M',
+  fireworks: 'kokoro',
+  openai: 'gpt-4o-mini-tts',
+  elevenlabs: 'eleven_multilingual_v2',
+  google: 'gemini-2.5-flash-preview-tts',
+  azure: 'en-US-JennyNeural',
+  groq: 'playai-tts',
+  deepgram: 'aura-asteria-en',
+  openrouter: 'openai/gpt-4o-mini-tts-2025-12-15',
+  custom: '',
+  edge: 'ru-RU-SvetlanaNeural',
+  piper: '',
+  espeak: 'ru',
+}
+
+export const DEFAULT_VOICES = {
+  kokoro: 'af_bella',
+  f5: 'default',
+  // MiMo voices use Chinese names; 冰糖 is their default.
+  mimo: '冰糖',
+  minimax: '',
+  siliconflow: 'FunAudioLLM/CosyVoice2-0.5B:alex',
+  deepinfra: 'af_bella',
+  fireworks: 'af_bella',
+  openai: 'alloy',
+  elevenlabs: '21m00Tcm4TlvDq8ikWAM',
+  google: 'Kore',
+  azure: 'en-US-JennyNeural',
+  groq: 'Fritz-PlayAI',
+  deepgram: '',
+  openrouter: 'alloy',
+  custom: '',
+  edge: 'ru-RU-SvetlanaNeural',
+  piper: '',
+  espeak: 'ru',
+}
+
+

package/lib/providers.js

@@ -1,66 +1,8 @@
 import { edgeSpeak, espeakSpeak, minimaxSpeak, piperSpeak } from './local.js'
 import { KokoroEngine } from './engines/kokoro.js'
 import { F5Engine } from './engines/f5.js'
-
-export const PROVIDER_KEYS = [
-  'kokoro', 'f5',
-  'openai', 'elevenlabs', 'google', 'azure', 'groq', 'deepgram', 'openrouter',
-  'siliconflow', 'deepinfra', 'fireworks', 'mimo', 'custom',
-  'edge', 'piper', 'espeak', 'minimax',
-]
-
-// OpenAI-compatible providers share /audio/speech; they differ by base URL,
-// model, and key name. Each URL was probed without a key and returned 401.
-export const OPENAI_COMPATIBLE = {
-  siliconflow: { baseUrl: 'https://api.siliconflow.cn/v1', keyEnv: 'SILICONFLOW_API_KEY' },
-  deepinfra: { baseUrl: 'https://api.deepinfra.com/v1/openai', keyEnv: 'DEEPINFRA_API_KEY' },
-  fireworks: { baseUrl: 'https://api.fireworks.ai/inference/v1', keyEnv: 'FIREWORKS_API_KEY' },
-  // Custom endpoint: base URL and key name come from settings.
-  custom: { baseUrl: '', keyEnv: 'CUSTOM_TTS_API_KEY' },
-}
-
-export const DEFAULT_MODELS = {
-  kokoro: 'hexgrad/Kokoro-82M',
-  f5: 'F5-TTS',
-  mimo: 'mimo-v2.5-tts',
-  minimax: '',
-  siliconflow: 'FunAudioLLM/CosyVoice2-0.5B',
-  deepinfra: 'hexgrad/Kokoro-82M',
-  fireworks: 'kokoro',
-  openai: 'gpt-4o-mini-tts',
-  elevenlabs: 'eleven_multilingual_v2',
-  google: 'gemini-2.5-flash-preview-tts',
-  azure: 'en-US-JennyNeural',
-  groq: 'playai-tts',
-  deepgram: 'aura-asteria-en',
-  openrouter: 'openai/gpt-4o-mini-tts-2025-12-15',
-  custom: '',
-  edge: 'ru-RU-SvetlanaNeural',
-  piper: '',
-  espeak: 'ru',
-}
-
-export const DEFAULT_VOICES = {
-  kokoro: 'af_bella',
-  f5: 'default',
-  // MiMo voices use Chinese names; 冰糖 is their default.
-  mimo: '冰糖',
-  minimax: '',
-  siliconflow: 'FunAudioLLM/CosyVoice2-0.5B:alex',
-  deepinfra: 'af_bella',
-  fireworks: 'af_bella',
-  openai: 'alloy',
-  elevenlabs: '21m00Tcm4TlvDq8ikWAM',
-  google: 'Kore',
-  azure: 'en-US-JennyNeural',
-  groq: 'Fritz-PlayAI',
-  deepgram: '',
-  openrouter: 'alloy',
-  custom: '',
-  edge: 'ru-RU-SvetlanaNeural',
-  piper: '',
-  espeak: 'ru',
-}
+import { PROVIDER_KEYS, OPENAI_COMPATIBLE, DEFAULT_MODELS, DEFAULT_VOICES } from './providers/constants.js'
+export { PROVIDER_KEYS, OPENAI_COMPATIBLE, DEFAULT_MODELS, DEFAULT_VOICES }
 
 function pick(map, models, key) {
   const chosen = models && typeof models[key] === 'string' ? models[key].trim() : ''
@@ -179,7 +121,7 @@ export function makeProviders(deps, req) {
       && data.choices[0].message && data.choices[0].message.audio
       && data.choices[0].message.audio.data
     if (typeof encoded !== 'string' || !encoded) {
-      return { ok: false, provider: 'mimo', reason: 'в ответе нет choices[0].message.audio.data' }
+      return { ok: false, provider: 'mimo', reason: 'response missing choices[0].message.audio.data' }
     }
     const audio = Buffer.from(encoded, 'base64')
     return {

package/lib/routes.js

@@ -1,5 +1,5 @@
 import { writeJson, readBody, isTrustedSettingsRequest } from './http-util.js'
-import { addStreamSubscriber, removeStreamSubscriber } from './stream-hub.js'
+import { addStreamSubscriber, removeStreamSubscriber, streamSubscriberCount } from './stream-hub.js'
 import { pendingKeyWrites, stripSecretsFromConfig, needsApiKey } from './keys.js'
 import { PROVIDER_KEYS } from './providers.js'
 
@@ -21,6 +21,9 @@ export function registerHttpRoutes(ctx, api) {
     storeProviderKey,
     clearProviderKey,
     pending,
+    getSettingsApi,
+    validateConfig,
+    breakerSnapshot,
   } = api
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
@@ -42,6 +45,8 @@ export function registerHttpRoutes(ctx, api) {
         chain: cfg.chain,
         roles: cfg.roles,
         providers: PROVIDER_KEYS,
+        sseClients: streamSubscriberCount(),
+        breaker: typeof breakerSnapshot === 'function' ? breakerSnapshot() : [],
       })
     },
   }), 'dsh-tts: /status route')
@@ -107,7 +112,11 @@ export function registerHttpRoutes(ctx, api) {
         // Fire installation in background or await initial start
         modelManager.installModel(engine).catch(() => {})
         const current = await modelManager.getStatus(engine)
-        writeJson(res, 200, { ok: true, model: current })
+        writeJson(res, 200, {
+          ok: true,
+          model: current,
+          note: 'Weights only. Neural inference runtime is not bundled; speech still requires Edge, Piper, or eSpeak.',
+        })
       } catch (err) {
         writeJson(res, 500, { ok: false, error: String(err && err.message || err) })
       }
@@ -130,7 +139,7 @@ export function registerHttpRoutes(ctx, api) {
       try {
         const raw = await readBody(req, 16 * 1024)
         body = JSON.parse(raw.toString('utf8') || '{}')
-      } catch { body = {} }
+      } catch { /* missing body treated as empty */ body = {} }
       const engine = String(body.engine || '').trim()
       if (!engine) {
         writeJson(res, 400, { ok: false, error: { code: 'param', message: 'missing engine parameter' } })
@@ -158,7 +167,7 @@ export function registerHttpRoutes(ctx, api) {
           voiceInstalled = ctx.webServer.hasRoute('/dsh-voice/status')
           messengerInstalled = ctx.webServer.hasRoute('/dsh-messenger-gateway/status')
         }
-      } catch {}
+      } catch { /* ignore malformed client frame */ }
 
       // Runtime routes are the only reliable signal. Do not probe ../ siblings
       // or node_modules layouts — they lie outside a normal npm install.
@@ -235,7 +244,7 @@ export function registerHttpRoutes(ctx, api) {
     path: '/dsh-tts/stats',
     handler: async (req, res) => {
       if (req.method === 'GET') {
-        writeJson(res, 200, { ok: true, total: stats.total, cacheHits: stats.cacheHits, errors: stats.errors, providers: stats.providers })
+        writeJson(res, 200, { ok: true, total: stats.total, cacheHits: stats.cacheHits, errors: stats.errors, providers: stats.providers, breaker: typeof breakerSnapshot === 'function' ? breakerSnapshot() : [] })
         return
       }
       if (req.method !== 'DELETE') {
@@ -270,6 +279,7 @@ export function registerHttpRoutes(ctx, api) {
         writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'dsh-tts: settings writes are same-origin only' } })
         return
       }
+      const settingsApi = typeof getSettingsApi === 'function' ? getSettingsApi() : null
       if (!settingsApi) {
         writeJson(res, 503, { ok: false, error: { code: 'settings', message: 'settings not ready' } })
         return
@@ -280,7 +290,7 @@ export function registerHttpRoutes(ctx, api) {
         return
       }
       let payload
-      try { payload = JSON.parse(raw.toString('utf8') || '{}') } catch {
+      try { payload = JSON.parse(raw.toString('utf8') || '{}') } catch { /* invalid JSON treated as empty */
         writeJson(res, 400, { ok: false, error: { code: 'json', message: 'invalid json' } })
         return
       }
@@ -290,7 +300,7 @@ export function registerHttpRoutes(ctx, api) {
       const keys = pendingKeyWrites(payload && payload.keys)
       const stripped = stripSecretsFromConfig(payload)
       let parsed
-      try { parsed = Config(stripped) } catch (e) {
+      try { parsed = validateConfig(stripped) } catch (e) {
         writeJson(res, 400, { ok: false, error: { code: 'schema', message: String(e && e.message || e) } })
         return
       }
@@ -325,7 +335,7 @@ export function registerHttpRoutes(ctx, api) {
           writeJson(res, 400, { ok: false, error: { code: 'body', message: e.message } })
           return
         }
-        try { payload = JSON.parse(raw.toString('utf8') || '{}') } catch {
+        try { payload = JSON.parse(raw.toString('utf8') || '{}') } catch { /* invalid JSON treated as empty */
           writeJson(res, 400, { ok: false, error: { code: 'json', message: 'invalid json' } })
           return
         }
@@ -375,7 +385,7 @@ export function registerHttpRoutes(ctx, api) {
         writeJson(res, 400, { ok: false, error: { code: 'body', message: e.message } }); return
       }
       let payload
-      try { payload = JSON.parse(raw.toString('utf8') || '{}') } catch { payload = {} }
+      try { payload = JSON.parse(raw.toString('utf8') || '{}') } catch { /* invalid JSON treated as empty */ /* invalid JSON treated as empty */ payload = {} }
       const text = cleanText(payload.text, live())
       if (!text) { writeJson(res, 400, { ok: false, error: { code: 'no-text', message: 'no text' } }); return }
       const cfg = live()

package/lib/stream-hub.js

@@ -1,31 +1,83 @@
 // SSE subscriber hub for /dsh-tts/stream.
 
 const subscribers = new Set()
+let heartbeatTimer = null
+
+function detach(res) {
+  try {
+    if (res.__dtsOnClose) res.off('close', res.__dtsOnClose)
+    if (res.__dtsOnError) res.off('error', res.__dtsOnError)
+  } catch { /* listeners may already be gone */ }
+  res.__dtsOnClose = null
+  res.__dtsOnError = null
+}
+
+function safeWrite(res, payload) {
+  try {
+    res.write(payload)
+    return true
+  } catch {
+    subscribers.delete(res)
+    detach(res)
+    return false
+  }
+}
+
+function ensureHeartbeat() {
+  if (heartbeatTimer || typeof setInterval !== 'function') return
+  heartbeatTimer = setInterval(() => {
+    if (!subscribers.size) {
+      clearInterval(heartbeatTimer)
+      heartbeatTimer = null
+      return
+    }
+    for (const res of [...subscribers]) {
+      safeWrite(res, ': ping\n\n')
+    }
+  }, 15000)
+  if (heartbeatTimer.unref) heartbeatTimer.unref()
+}
 
 export function addStreamSubscriber(res) {
   subscribers.add(res)
+  const onClose = () => {
+    subscribers.delete(res)
+    detach(res)
+  }
+  res.__dtsOnClose = onClose
+  res.__dtsOnError = onClose
+  try {
+    res.on('close', onClose)
+    res.on('error', onClose)
+  } catch { /* non-node response object in tests */ }
+  ensureHeartbeat()
 }
 
 export function removeStreamSubscriber(res) {
   subscribers.delete(res)
+  detach(res)
 }
 
 export function broadcastStream(type, item) {
-  const payload = `event: ${type}\ndata: ${JSON.stringify(item)}\n\n`
-  for (const res of subscribers) {
-    try {
-      res.write(payload)
-    } catch {
-      subscribers.delete(res)
-    }
+  const payload = 'event: ' + type + '\ndata: ' + JSON.stringify(item) + '\n\n'
+  for (const res of [...subscribers]) {
+    safeWrite(res, payload)
   }
 }
 
+export function streamSubscriberCount() {
+  return subscribers.size
+}
+
 export function clearStreamSubscribers() {
-  for (const res of subscribers) {
+  for (const res of [...subscribers]) {
     try {
       res.end()
     } catch { /* already closed */ }
   }
   subscribers.clear()
-}
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer)
+    heartbeatTimer = null
+  }
+}

package/lib/text.js

@@ -30,7 +30,7 @@ export function applyNarrationFilters(text, cfg) {
   if (cfg && cfg.removeRegex) {
     try {
       out = out.replace(new RegExp(cfg.removeRegex, 'g'), ' ')
-    } catch (badUserRegex) { /* кривая регулярка не роняет озвучку */ }
+    } catch (badUserRegex) { /* bad user regex must not break speech */ }
   }
   if (cfg && cfg.skipActions) out = out.replace(/(^|\s)\*[^*\n]+\*/g, '$1')
   if (cfg && cfg.narrateQuotesOnly) {
@@ -100,7 +100,7 @@ export function applyPronunciation(text, rules, language, enableBuiltinIt = fals
       else if (rule.whole) re = new RegExp('(?<![\\p{L}\\p{N}])' + escapeRe(rule.from) + '(?![\\p{L}\\p{N}])', 'gu')
       else re = new RegExp(escapeRe(rule.from), 'g')
       out = out.replace(re, to)
-    } catch (badRule) { /* кривое правило не роняет озвучку */ }
+    } catch (badRule) { /* bad rule must not break speech */ }
   }
   return out
 }
@@ -174,7 +174,7 @@ export function restoreAbbreviations(text) {
 }
 
 /**
- * Режет текст на куски по границам предложений.
+ * Split text into chunks on sentence boundaries.
  *
  * Нужно, чтобы чтение начиналось почти сразу: длинный ответ синтезируется
  * целиком долго, а первое предложение — быстро. Куски короче нижнего порога

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-tts",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Text-to-speech for DeepSeek Harness: speak agent replies in the Web UI with a provider fallback chain (OpenAI, ElevenLabs, Google, Azure, Groq, Deepgram, OpenRouter, Edge, Piper, eSpeak).",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,9 @@
     "url": "https://github.com/GooDAnDReaDY/dsh-tts/issues"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs"
+    "test": "node --test test/*.test.mjs",
+    "build:client": "node scripts/build-client.mjs",
+    "pretest": "node scripts/build-client.mjs"
   },
   "dsh": {
     "bundle": {

package/scripts/build-client.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+// Concatenate lib/client-src fragments into lib/client.js (single ModuleLoader entry).
+import { readdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.dirname(path.dirname(fileURLToPath(import.meta.url)))
+const srcDir = path.join(root, 'lib', 'client-src')
+const outFile = path.join(root, 'lib', 'client.js')
+
+const files = (await readdir(srcDir)).filter((f) => f.endsWith('.js')).sort()
+if (files.length === 0) throw new Error('no client-src fragments')
+let out = ''
+for (const f of files) {
+  out += await readFile(path.join(srcDir, f), 'utf8')
+  if (!out.endsWith('\n')) out += '\n'
+}
+await writeFile(outFile, out, 'utf8')
+console.log(`built lib/client.js from ${files.length} fragments (${out.length} bytes)`)