@goodandready/dsh-tts 0.1.1

package/lib/index.js

@@ -0,0 +1,458 @@
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { runChain } from './chain.js'
+import { makeProviders, PROVIDER_KEYS, DEFAULT_MODELS, DEFAULT_VOICES } from './providers.js'
+import { assistantText, stripForSpeech } from './text.js'
+import {
+  CLOUD_PROVIDERS,
+  assertCredentialRef,
+  keyEnvName,
+  needsApiKey,
+  pendingKeyWrites,
+  publicConfig,
+  stripSecretsFromConfig,
+} from './keys.js'
+
+export const name = 'dsh-tts'
+export const inject = ['tools', 'credentials', 'webServer', 'settings']
+
+const NS = 'dsh-tts'
+
+const ChainEntry = z.object({
+  provider: z.string().default('espeak')
+    .description(`Provider key. One of: ${PROVIDER_KEYS.join(', ')}.`),
+  model: z.string().default('')
+    .description('Model override. Empty means the provider default.'),
+  voice: z.string().default('')
+    .description('Voice override. Empty means the provider default.'),
+})
+
+export const Config = z.object({
+  speakReplies: z.boolean().default(false)
+    .description('When on, speak each finished agent reply in the Web UI.'),
+  language: z.string().default('ru'),
+  maxChars: z.number().default(4000)
+    .description('Longer replies are truncated before synthesis.'),
+  chain: z.array(ChainEntry)
+    .default([
+      { provider: 'edge', model: '', voice: 'ru-RU-SvetlanaNeural' },
+      { provider: 'piper', model: '', voice: '' },
+      { provider: 'espeak', model: '', voice: 'ru' },
+    ])
+    .description('Fallback chain. Order is the order of attempts. A provider without a key is skipped.'),
+  openaiKeyEnv: z.string().default('OPENAI_API_KEY'),
+  openaiBaseUrl: z.string().default('https://api.openai.com/v1'),
+  elevenlabsKeyEnv: z.string().default('ELEVENLABS_API_KEY'),
+  googleKeyEnv: z.string().default('GEMINI_API_KEY'),
+  azureKeyEnv: z.string().default('AZURE_SPEECH_KEY'),
+  azureRegion: z.string().default('')
+    .description('Azure Speech region, e.g. eastus. Required for the azure provider.'),
+  groqKeyEnv: z.string().default('GROQ_API_KEY'),
+  deepgramKeyEnv: z.string().default('DEEPGRAM_API_KEY'),
+  openrouterKeyEnv: z.string().default('OPENROUTER_API_KEY'),
+  edgeBin: z.string().default('edge-tts')
+    .description('edge-tts CLI. Looked up in PATH unless an absolute path is given.'),
+  piperBin: z.string().default('piper'),
+  piperModel: z.string().default('')
+    .description('Path to a Piper ONNX model. The piper provider is skipped while this is empty.'),
+  espeakBin: z.string().default('espeak-ng'),
+  timeoutMs: z.number().default(60000),
+  maxQueue: z.number().default(8),
+})
+
+function writeJson(res, code, body) {
+  try {
+    res.writeHead(code, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' })
+    res.end(JSON.stringify(body))
+  } catch { /* socket closed */ }
+}
+
+function readBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (c) => {
+      size += c.length
+      if (size > maxBytes) { reject(new Error('body too large')); req.destroy(); return }
+      chunks.push(c)
+    })
+    req.on('end', () => resolve(Buffer.concat(chunks)))
+    req.on('error', reject)
+  })
+}
+
+/** Reject cross-site POSTs. Do not require loopback or Origin==Host: the Web UI is used over LAN and reverse proxies. */
+function isTrustedSettingsRequest(request) {
+  return request.headers['sec-fetch-site'] !== 'cross-site'
+}
+
+let utteranceSeq = 0
+
+export function apply(ctx, config) {
+  let getConfig = () => config
+  const live = () => Config(structuredClone(getConfig() ?? {})) ?? config
+
+  let settingsApi
+  ctx.inject(['settings'], (sctx) => {
+    const scope = sctx.settings.register(NS, Config, { base: config })
+    settingsApi = scope
+    getConfig = () => scope.get() ?? config
+    sctx.effect(() => () => {
+      settingsApi = undefined
+      getConfig = () => config
+    })
+  })
+
+  const pending = []
+  const collectors = new Map()
+
+  async function resolveKey(ref) {
+    try {
+      const resolved = await ctx.credentials.resolve(credentialRef(ref))
+      if (resolved && resolved.value) return resolved.value
+    } catch { /* fall through to env */ }
+    return process.env[ref] || ''
+  }
+
+  async function describeProvider(provider) {
+    const ref = keyEnvName(live(), provider)
+    const base = { provider, ref, configured: false, writable: true }
+    if (!ref) return base
+    try {
+      if (typeof ctx.credentials.describe === 'function') {
+        const d = await ctx.credentials.describe(credentialRef(ref))
+        return {
+          provider,
+          ref,
+          configured: !!(d && d.configured),
+          writable: d && d.writable === false ? false : true,
+        }
+      }
+      const resolved = await ctx.credentials.resolve(credentialRef(ref))
+      return { provider, ref, configured: !!(resolved && resolved.value), writable: true }
+    } catch {
+      return base
+    }
+  }
+
+  async function credentialsView() {
+    const out = {}
+    for (const provider of CLOUD_PROVIDERS) {
+      out[provider] = await describeProvider(provider)
+    }
+    return out
+  }
+
+  async function storeProviderKey(provider, value) {
+    if (!needsApiKey(provider)) {
+      throw new Error(`${provider} does not take an API key`)
+    }
+    const trimmed = String(value || '').trim()
+    if (!trimmed) {
+      throw new Error('an empty key cannot be stored')
+    }
+    if (typeof ctx.credentials.set !== 'function') {
+      throw new Error('no credentials service is mounted')
+    }
+    const ref = assertCredentialRef(keyEnvName(live(), provider))
+    await ctx.credentials.set(credentialRef(ref), trimmed)
+    return ref
+  }
+
+  async function clearProviderKey(provider) {
+    if (!needsApiKey(provider)) {
+      throw new Error(`${provider} does not take an API key`)
+    }
+    if (typeof ctx.credentials.unset !== 'function') {
+      throw new Error('no credentials service is mounted')
+    }
+    const ref = assertCredentialRef(keyEnvName(live(), provider))
+    await ctx.credentials.unset(credentialRef(ref))
+    return ref
+  }
+
+  async function configResponse() {
+    return {
+      ok: true,
+      config: publicConfig(live()),
+      credentials: await credentialsView(),
+    }
+  }
+
+  async function synthesize(rawText, cfg, signal) {
+    const text = stripForSpeech(rawText, cfg.maxChars)
+    if (!text) throw new Error('nothing to speak')
+    const models = {}
+    const voices = {}
+    const order = []
+    for (const entry of Array.isArray(cfg.chain) ? cfg.chain : []) {
+      if (!PROVIDER_KEYS.includes(entry.provider)) continue
+      order.push(entry.provider)
+      models[entry.provider] = entry.model || DEFAULT_MODELS[entry.provider]
+      voices[entry.provider] = entry.voice || DEFAULT_VOICES[entry.provider]
+    }
+    const providers = makeProviders(
+      { resolveKey, fetchImpl: fetch, cfg },
+      { text, lang: cfg.language, signal, models, voices },
+    )
+    return runChain(order, providers)
+  }
+
+  function enqueue(item) {
+    pending.push(item)
+    const max = live().maxQueue || 8
+    while (pending.length > max) pending.shift()
+  }
+
+  ctx.effect(() => ctx.on('session/event', (session, event) => {
+    const cfg = live()
+    if (!cfg.speakReplies) return
+    const sid = session && session.id
+    if (!sid) return
+    if (event.type === 'assistant/message') {
+      const text = assistantText(event.data && event.data.message)
+      if (!text) return
+      const cur = collectors.get(sid) || { parts: [] }
+      cur.parts.push(text)
+      collectors.set(sid, cur)
+      return
+    }
+    if (event.type !== 'turn/end') return
+    const cur = collectors.get(sid)
+    collectors.delete(sid)
+    const raw = cur && Array.isArray(cur.parts) ? cur.parts.join('\n') : ''
+    const text = stripForSpeech(raw, cfg.maxChars)
+    if (!text) return
+    const id = `u${++utteranceSeq}`
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), cfg.timeoutMs)
+    synthesize(text, cfg, controller.signal)
+      .then((out) => {
+        enqueue({
+          id,
+          sessionId: sid,
+          provider: out.provider,
+          mime: out.mime,
+          audioBase64: Buffer.from(out.audio).toString('base64'),
+          tookMs: out.tookMs,
+        })
+      })
+      .catch((err) => {
+        enqueue({
+          id,
+          sessionId: sid,
+          error: String(err && err.message || err),
+        })
+      })
+      .finally(() => clearTimeout(timer))
+  }), 'dsh-tts: speak finished replies')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-tts/status',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') { writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } }); return }
+      const cfg = live()
+      writeJson(res, 200, {
+        ok: true,
+        speakReplies: cfg.speakReplies,
+        language: cfg.language,
+        chain: cfg.chain,
+        providers: PROVIDER_KEYS,
+      })
+    },
+  }), 'dsh-tts: /status route')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-tts/config',
+    handler: async (req, res) => {
+      if (req.method === 'GET') {
+        writeJson(res, 200, await configResponse())
+        return
+      }
+      if (req.method !== 'PUT' && req.method !== 'POST') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET or PUT' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'dsh-tts: settings writes are same-origin only' } })
+        return
+      }
+      if (!settingsApi) {
+        writeJson(res, 503, { ok: false, error: { code: 'settings', message: 'settings not ready' } })
+        return
+      }
+      let raw
+      try { raw = await readBody(req, 256 * 1024) } catch (e) {
+        writeJson(res, 400, { ok: false, error: { code: 'body', message: e.message } })
+        return
+      }
+      let payload
+      try { payload = JSON.parse(raw.toString('utf8') || '{}') } catch {
+        writeJson(res, 400, { ok: false, error: { code: 'json', message: 'invalid json' } })
+        return
+      }
+      if (payload && typeof payload.config === 'object') {
+        payload = { ...payload.config, keys: payload.keys }
+      }
+      const keys = pendingKeyWrites(payload && payload.keys)
+      const stripped = stripSecretsFromConfig(payload)
+      let parsed
+      try { parsed = Config(stripped) } catch (e) {
+        writeJson(res, 400, { ok: false, error: { code: 'schema', message: String(e && e.message || e) } })
+        return
+      }
+      try {
+        for (const item of keys) {
+          await storeProviderKey(item.provider, item.value)
+        }
+        await settingsApi.replace(parsed)
+        writeJson(res, 200, await configResponse())
+      } catch (e) {
+        writeJson(res, 500, { ok: false, error: { code: 'save', message: String(e && e.message || e) } })
+      }
+    },
+  }), 'dsh-tts: /config route')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-tts/credential',
+    handler: async (req, res) => {
+      if (req.method !== 'PUT' && req.method !== 'DELETE') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'PUT or DELETE only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'dsh-tts: keys are same-origin only' } })
+        return
+      }
+      let payload = {}
+      if (req.method === 'PUT' || (req.headers['content-length'] && Number(req.headers['content-length']) > 0)) {
+        let raw
+        try { raw = await readBody(req, 16 * 1024) } catch (e) {
+          writeJson(res, 400, { ok: false, error: { code: 'body', message: e.message } })
+          return
+        }
+        try { payload = JSON.parse(raw.toString('utf8') || '{}') } catch {
+          writeJson(res, 400, { ok: false, error: { code: 'json', message: 'invalid json' } })
+          return
+        }
+      }
+      const provider = typeof payload.provider === 'string' ? payload.provider.trim() : ''
+      if (!needsApiKey(provider)) {
+        writeJson(res, 400, { ok: false, error: { code: 'provider', message: 'unknown cloud provider' } })
+        return
+      }
+      try {
+        if (req.method === 'DELETE') {
+          const ref = await clearProviderKey(provider)
+          writeJson(res, 200, { ok: true, ref, credentials: await credentialsView() })
+          return
+        }
+        const ref = await storeProviderKey(provider, payload.value)
+        writeJson(res, 200, { ok: true, ref, credentials: await credentialsView() })
+      } catch (e) {
+        writeJson(res, 400, { ok: false, error: { code: 'credential', message: String(e && e.message || e) } })
+      }
+    },
+  }), 'dsh-tts: /credential route')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-tts/pending',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') { writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } }); return }
+      const url = new URL(req.url || '/', 'http://127.0.0.1')
+      const after = url.searchParams.get('after') || ''
+      let items = pending.slice()
+      if (after) {
+        const idx = items.findIndex((x) => x.id === after)
+        items = idx >= 0 ? items.slice(idx + 1) : items
+      }
+      writeJson(res, 200, { ok: true, items })
+    },
+  }), 'dsh-tts: /pending route')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-tts/speak',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') { writeJson(res, 405, { ok: false, error: { code: 'method', message: 'POST only' } }); return }
+      let raw
+      try { raw = await readBody(req, 256 * 1024) } catch (e) {
+        writeJson(res, 400, { ok: false, error: { code: 'body', message: e.message } }); return
+      }
+      let payload
+      try { payload = JSON.parse(raw.toString('utf8') || '{}') } catch { payload = {} }
+      const text = stripForSpeech(payload.text, live().maxChars)
+      if (!text) { writeJson(res, 400, { ok: false, error: { code: 'no-text', message: 'no text' } }); return }
+      const cfg = live()
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), cfg.timeoutMs)
+      try {
+        const out = await synthesize(text, cfg, controller.signal)
+        writeJson(res, 200, {
+          ok: true,
+          provider: out.provider,
+          mime: out.mime,
+          audioBase64: Buffer.from(out.audio).toString('base64'),
+          tookMs: out.tookMs,
+        })
+      } catch (e) {
+        writeJson(res, 502, { ok: false, error: { code: 'chain', message: String(e && e.message || e) } })
+      } finally {
+        clearTimeout(timer)
+      }
+    },
+  }), 'dsh-tts: /speak route')
+
+  ctx.tools.register(
+    defineTool({
+      name: 'speak_text',
+      description:
+        'Synthesize speech from text using the dsh-tts provider fallback chain. '
+        + 'Returns audio as base64 plus the provider that succeeded. '
+        + 'Use when the user asks to hear text; do not dump the audio into the model context.',
+      parameters: {
+        text: { type: 'string', required: true, description: 'Text to speak.' },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            ok: { type: 'boolean' },
+            provider: { type: 'string' },
+            mime: { type: 'string' },
+            bytes: { type: 'number' },
+            tookMs: { type: 'number' },
+            error: { type: 'string' },
+          },
+        },
+        render: (_args, value) => [{
+          type: 'text',
+          text: value && value.ok
+            ? `Spoken with ${value.provider} (${value.mime}, ${value.bytes || 0} bytes).`
+            : `TTS failed: ${value && value.error ? value.error : 'unknown'}`,
+        }],
+      },
+      execute: async (args, exec) => {
+        const cfg = live()
+        try {
+          const out = await synthesize(String(args.text || ''), cfg, exec.signal)
+          return {
+            ok: true,
+            provider: out.provider,
+            mime: out.mime,
+            bytes: out.audio.length,
+            tookMs: out.tookMs,
+          }
+        } catch (e) {
+          return { ok: false, error: String(e && e.message || e) }
+        }
+      },
+    }),
+  )
+}

package/lib/keys.js

@@ -0,0 +1,74 @@
+export const CLOUD_PROVIDERS = [
+  'openai', 'elevenlabs', 'google', 'azure', 'groq', 'deepgram', 'openrouter',
+]
+
+export const KEY_ENV_FIELD = {
+  openai: 'openaiKeyEnv',
+  elevenlabs: 'elevenlabsKeyEnv',
+  google: 'googleKeyEnv',
+  azure: 'azureKeyEnv',
+  groq: 'groqKeyEnv',
+  deepgram: 'deepgramKeyEnv',
+  openrouter: 'openrouterKeyEnv',
+}
+
+export const DEFAULT_KEY_ENV = {
+  openai: 'OPENAI_API_KEY',
+  elevenlabs: 'ELEVENLABS_API_KEY',
+  google: 'GEMINI_API_KEY',
+  azure: 'AZURE_SPEECH_KEY',
+  groq: 'GROQ_API_KEY',
+  deepgram: 'DEEPGRAM_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
+}
+
+const REF_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+
+export function needsApiKey(provider) {
+  return Object.prototype.hasOwnProperty.call(KEY_ENV_FIELD, provider)
+}
+
+export function keyEnvName(cfg, provider) {
+  const field = KEY_ENV_FIELD[provider]
+  if (!field) return ''
+  const name = String((cfg && cfg[field]) || '').trim()
+  return name || DEFAULT_KEY_ENV[provider] || ''
+}
+
+export function assertCredentialRef(ref) {
+  if (!REF_PATTERN.test(ref)) {
+    throw new Error('credential ref must be an environment variable name')
+  }
+  return ref
+}
+
+/** Drop write-only key material so it never lands in plugin settings. */
+export function stripSecretsFromConfig(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return {}
+  const config = { ...payload }
+  delete config.keys
+  delete config.credentials
+  for (const key of Object.keys(config)) {
+    if (/KeyEnv$/.test(key)) continue
+    if (/(^|.*)(apiKey|api_key|secret|token|password)$/i.test(key) || /Key$/.test(key)) {
+      delete config[key]
+    }
+  }
+  return config
+}
+
+export function pendingKeyWrites(keys) {
+  const out = []
+  if (!keys || typeof keys !== 'object') return out
+  for (const provider of Object.keys(keys)) {
+    if (!needsApiKey(provider)) continue
+    const value = typeof keys[provider] === 'string' ? keys[provider].trim() : ''
+    if (!value) continue
+    out.push({ provider, value })
+  }
+  return out
+}
+
+export function publicConfig(cfg) {
+  return stripSecretsFromConfig(cfg)
+}

package/lib/local.js

@@ -0,0 +1,83 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+function spawnCollect(bin, args, { stdinText, timeoutMs } = {}) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(bin, args, { stdio: ['pipe', 'pipe', 'pipe'] })
+    const out = []
+    const err = []
+    const timer = setTimeout(() => {
+      try { proc.kill('SIGKILL') } catch { /* gone */ }
+      reject(new Error(`${bin} timed out`))
+    }, timeoutMs || 60000)
+    proc.stdout.on('data', (c) => out.push(c))
+    proc.stderr.on('data', (c) => err.push(c))
+    proc.on('error', (e) => {
+      clearTimeout(timer)
+      reject(new Error(`${bin} unavailable: ${e.message}`))
+    })
+    proc.on('close', (code) => {
+      clearTimeout(timer)
+      const stdout = Buffer.concat(out)
+      const stderr = Buffer.concat(err).toString('utf8').slice(0, 240)
+      if (code !== 0) {
+        reject(new Error(`${bin} exit ${code}: ${stderr}`))
+        return
+      }
+      resolve(stdout)
+    })
+    if (stdinText != null) {
+      proc.stdin.on('error', () => {})
+      proc.stdin.end(Buffer.from(String(stdinText), 'utf8'))
+    } else {
+      proc.stdin.end()
+    }
+  })
+}
+
+export async function espeakSpeak(text, { bin, voice, timeoutMs }) {
+  const bytes = await spawnCollect(bin || 'espeak-ng', [
+    '-v', voice || 'ru',
+    '--stdout',
+    '-s', '165',
+  ], { stdinText: text, timeoutMs })
+  if (!bytes || bytes.length < 64) throw new Error('espeak produced empty audio')
+  return { audio: bytes, mime: 'audio/wav' }
+}
+
+export async function piperSpeak(text, { bin, model, timeoutMs }) {
+  if (!model) throw new Error('piper model path is empty')
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'dsh-tts-piper-'))
+  const outFile = path.join(dir, 'out.wav')
+  try {
+    await spawnCollect(bin || 'piper', [
+      '--model', model,
+      '--output_file', outFile,
+    ], { stdinText: text, timeoutMs })
+    const bytes = await readFile(outFile)
+    if (!bytes || bytes.length < 64) throw new Error('piper produced empty audio')
+    return { audio: bytes, mime: 'audio/wav' }
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+
+export async function edgeSpeak(text, { bin, voice, timeoutMs }) {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'dsh-tts-edge-'))
+  const outFile = path.join(dir, 'out.mp3')
+  try {
+    await spawnCollect(bin || 'edge-tts', [
+      '--voice', voice || 'ru-RU-SvetlanaNeural',
+      '--text', text,
+      '--write-media', outFile,
+    ], { timeoutMs })
+    const bytes = await readFile(outFile)
+    if (!bytes || bytes.length < 32) throw new Error('edge-tts produced empty audio')
+    return { audio: bytes, mime: 'audio/mpeg' }
+  } finally {
+    await rm(dir, { recursive: true, force: true })
+  }
+}
+