@goodandready/dsh-tts 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-tts contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# dsh-tts
+
+Text-to-speech for the DeepSeek Harness Web GUI. When **Speak agent replies**
+is on, each finished assistant turn is synthesized on the host and played in
+the browser. API keys never reach the browser.
+
+A later messenger hub can call the same host chain (`POST /dsh-tts/speak` or
+the `speak_text` tool). This package does not talk to Telegram itself.
+
+## Install
+
+```bash
+# From npm (after a GitHub/npm release):
+dsh plugin --profile web add @goodandready/dsh-tts
+
+# From a local checkout:
+dsh plugin --profile web add file:/path/to/dsh-tts
+```
+
+Restart the Web UI, then hard-refresh the browser.
+
+## Configure
+
+Settings -> **Speech**:
+
+- **Speak agent replies** -- off by default.
+- **Provider chain** -- pick a provider, paste its API key in that row, then
+  Save (or leave the key field). The value is written to the host credentials
+  store immediately and is never sent back to the browser. The row shows
+  **Configured** / **Not set**. Leave the field blank to keep an existing key.
+  Local providers (`edge`, `piper`, `espeak`) have no key field.
+- A provider without a credential is skipped, not fatal.
+- Piper / eSpeak / edge-tts binaries and the Piper model path.
+
+Keys land in the same store the rest of DSH uses (credentials file, then the
+process environment). The plugin stores names, never values:
+
+```text
+OPENAI_API_KEY
+ELEVENLABS_API_KEY
+GEMINI_API_KEY
+AZURE_SPEECH_KEY
+GROQ_API_KEY
+DEEPGRAM_API_KEY
+OPENROUTER_API_KEY
+```
+
+Put additional keys in the same pool (`<PROVIDER>_API_KEY_2`, ...) if you use
+a key-rotation plugin.
+
+## Providers
+
+| Key | Service | Default model / voice | Credential |
+|---|---|---|---|
+| `openai` | OpenAI Audio Speech | `gpt-4o-mini-tts` / `alloy` | `OPENAI_API_KEY` |
+| `elevenlabs` | ElevenLabs | `eleven_multilingual_v2` | `ELEVENLABS_API_KEY` |
+| `google` | Gemini TTS | `gemini-2.5-flash-preview-tts` / `Kore` | `GEMINI_API_KEY` |
+| `azure` | Azure Speech | neural voice + region | `AZURE_SPEECH_KEY` + region |
+| `groq` | Groq PlayAI | `playai-tts` | `GROQ_API_KEY` |
+| `deepgram` | Deepgram Aura | `aura-asteria-en` | `DEEPGRAM_API_KEY` |
+| `openrouter` | OpenRouter `/audio/speech` | `openai/gpt-4o-mini-tts-2025-12-15` | `OPENROUTER_API_KEY` |
+| `edge` | Microsoft Edge Neural via `edge-tts` CLI | `ru-RU-SvetlanaNeural` | none |
+| `piper` | local Piper | path to an ONNX model | none |
+| `espeak` | eSpeak NG | voice `ru` | none |
+
+Default chain: `edge` → `piper` → `espeak`. Deepgram Aura does not list Russian;
+keep it below a Russian-capable voice if you speak Russian.
+
+### Free local / CLI providers
+
+```bash
+pip install edge-tts          # provides the `edge-tts` binary
+# piper: install the Piper binary and point Settings at your .onnx model
+sudo apt install espeak-ng    # or the equivalent package on your OS
+```
+
+## Tool
+
+`speak_text(text)` — synthesize with the same chain. The tool result is a short
+status line; it does not inject audio into the model history.
+
+## Routes
+
+| Route | Purpose |
+|---|---|
+| `GET /dsh-tts/status` | chain and whether auto-speak is on |
+| `GET` or `PUT /dsh-tts/config` | settings plus configured/writable/ref per cloud provider. PUT may include keys; values are stored as credentials and never echoed. |
+| `PUT` or `DELETE /dsh-tts/credential` | writes or clears one host credential immediately |
+| `GET /dsh-tts/pending?after=` | audio produced for finished replies |
+| `POST /dsh-tts/speak` | `{text}` -> `{ok, provider, mime, audioBase64}` |
+
+## Requirements
+
+- DeepSeek Harness with the Web GUI
+- Node 20+
+- Optional: `edge-tts`, `piper`, `espeak-ng` for the free providers
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,8 @@
+# dsh-tts bundle layer.
+#
+# `name` must stay the full npm package name: the client-modules registry
+# resolves the browser bundle by the loader entry name.
+- insert:
+    - id: dsh-tts
+      name: '@goodandready/dsh-tts'
+      config: {}

package/lib/chain.js

@@ -0,0 +1,33 @@
+// Fallback walk over a TTS provider chain. Pure: no cordis, no network.
+
+function normalizeError(err) {
+  const cause = err?.cause?.message || err?.message || String(err)
+  return cause.slice(0, 200)
+}
+
+/**
+ * @param order {string[]}
+ * @param providers {Record<string, () => Promise<{ok, provider?, audio?, mime?, reason?}>>}
+ */
+export async function runChain(order, providers) {
+  const t0 = Date.now()
+  const keys = (Array.isArray(order) ? order : []).filter((k) => typeof providers[k] === 'function')
+  const errors = []
+  for (const key of keys) {
+    try {
+      const out = await providers[key]()
+      if (out && out.ok && out.audio && out.audio.length > 0) {
+        return {
+          provider: out.provider || key,
+          audio: out.audio,
+          mime: out.mime || 'audio/mpeg',
+          tookMs: Date.now() - t0,
+        }
+      }
+      errors.push(`${(out && out.provider) || key}: ${(out && out.reason) || 'unknown'}`)
+    } catch (err) {
+      errors.push(`${key}: ${normalizeError(err)}`)
+    }
+  }
+  throw new Error(`all providers failed (${errors.join('; ')})`)
+}

package/lib/client.js

@@ -0,0 +1,310 @@
+window.__ModuleLoader__.load({
+  id: '@goodandready/dsh-tts',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    const React = require('react')
+    const NS = 'dsh-tts'
+    const PROVIDERS = [
+      'openai', 'elevenlabs', 'google', 'azure', 'groq', 'deepgram', 'openrouter',
+      'edge', 'piper', 'espeak',
+    ]
+    const CLOUD = {
+      openai: 1, elevenlabs: 1, google: 1, azure: 1, groq: 1, deepgram: 1, openrouter: 1,
+    }
+    const MODEL_HINT = {
+      openai: 'gpt-4o-mini-tts',
+      elevenlabs: 'eleven_multilingual_v2',
+      google: 'gemini-2.5-flash-preview-tts',
+      azure: 'region voice, e.g. en-US-JennyNeural',
+      groq: 'playai-tts',
+      deepgram: 'aura-asteria-en (no Russian)',
+      openrouter: 'openai/gpt-4o-mini-tts-2025-12-15',
+      edge: 'ru-RU-SvetlanaNeural',
+      piper: 'path to .onnx',
+      espeak: 'ru',
+    }
+
+    const SET_CSS =
+      '.dts-wrap{display:flex;flex-direction:column;gap:22px;padding:4px 0;max-width:720px}' +
+      '.dts-block{display:flex;flex-direction:column;gap:10px}' +
+      '.dts-h{font-size:14px;font-weight:600;color:var(--dsw-alias-label-primary)}' +
+      '.dts-sub{font-size:12px;color:var(--dsw-alias-label-secondary)}' +
+      '.dts-entry{display:flex;flex-direction:column;gap:8px;padding:10px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px}' +
+      '.dts-row{display:flex;gap:8px;align-items:center;flex-wrap:wrap}' +
+      '.dts-row select,.dts-row input,.dts-field input,.dts-field select{background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l1);color:var(--dsw-alias-label-primary);border-radius:6px;padding:6px 8px;font-size:13px}' +
+      '.dts-row .dts-model{flex:1;min-width:120px}' +
+      '.dts-row .dts-key{flex:1;min-width:180px}' +
+      '.dts-field{display:flex;flex-direction:column;gap:4px;font-size:12px;color:var(--dsw-alias-label-secondary)}' +
+      '.dts-mini{border:1px solid var(--dsw-alias-border-l2);background:transparent;color:var(--dsw-alias-label-primary);border-radius:6px;width:28px;height:28px;cursor:pointer;flex:none}' +
+      '.dts-save{background:var(--dsw-alias-brand-primary);color:#fff;border:none;border-radius:6px;padding:7px 14px;font-size:13px;cursor:pointer}' +
+      '.dts-ok{font-size:12px;color:var(--dsw-alias-state-success-primary)}' +
+      '.dts-bad{font-size:12px;color:var(--dsw-alias-state-error-primary)}' +
+      '.dts-badge{font-size:11px;padding:2px 8px;border-radius:999px;border:1px solid var(--dsw-alias-border-l2);color:var(--dsw-alias-label-secondary);white-space:nowrap}' +
+      '.dts-badge-on{color:var(--dsw-alias-state-success-primary);border-color:currentColor}' +
+      '.dts-link{background:none;border:none;color:var(--dsw-alias-label-secondary);cursor:pointer;font-size:12px;padding:0}'
+
+    const setCssId = 'dsh-tts/settings.module.css'
+    if (typeof document !== 'undefined' && !document.querySelector('style[data-plugin-css="' + setCssId + '"]')) {
+      const tag = document.createElement('style')
+      tag.textContent = SET_CSS
+      tag.setAttribute('data-plugin', 'dsh-tts')
+      tag.dataset.pluginCss = setCssId
+      document.head.appendChild(tag)
+    }
+
+    const player = { audio: null, after: '', enabled: false }
+
+    function playItem(item) {
+      if (!item || item.error || !item.audioBase64) return
+      try {
+        if (player.audio) { try { player.audio.pause() } catch (e) { /* ignore */ } }
+        const bin = atob(item.audioBase64)
+        const bytes = new Uint8Array(bin.length)
+        for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i)
+        const blob = new Blob([bytes], { type: item.mime || 'audio/mpeg' })
+        const url = URL.createObjectURL(blob)
+        const audio = new Audio(url)
+        player.audio = audio
+        audio.onended = () => { URL.revokeObjectURL(url) }
+        audio.play().catch(() => { URL.revokeObjectURL(url) })
+      } catch (e) { /* autoplay policy or decode */ }
+    }
+
+    async function pollPending() {
+      try {
+        const st = await fetch('/dsh-tts/status', { cache: 'no-store' })
+        if (!st.ok) return
+        const meta = await st.json()
+        player.enabled = !!(meta && meta.speakReplies)
+        if (!player.enabled) return
+        const res = await fetch('/dsh-tts/pending?after=' + encodeURIComponent(player.after || ''), { cache: 'no-store' })
+        if (!res.ok) return
+        const data = await res.json()
+        const items = data && Array.isArray(data.items) ? data.items : []
+        for (let i = 0; i < items.length; i++) {
+          const item = items[i]
+          player.after = item.id
+          playItem(item)
+        }
+      } catch (e) { /* host restarting */ }
+    }
+
+    function credOf(map, provider) {
+      return (map && map[provider]) || { configured: false, writable: true, ref: '' }
+    }
+
+    function ChainEditor(props) {
+      const rows = Array.isArray(props.value) ? props.value : []
+      const change = (i, patch) => {
+        const next = rows.map((r, k) => (k === i ? Object.assign({}, r, patch) : r))
+        props.onChange(next)
+      }
+      const move = (i, delta) => {
+        const j = i + delta
+        if (j < 0 || j >= rows.length) return
+        const next = rows.slice()
+        const tmp = next[i]; next[i] = next[j]; next[j] = tmp
+        props.onChange(next)
+      }
+      const remove = (i) => props.onChange(rows.filter((_, k) => k !== i))
+      const add = () => props.onChange(rows.concat([{ provider: 'espeak', model: '', voice: '' }]))
+      return React.createElement('div', { className: 'dts-block' },
+        rows.map((row, i) => {
+          const cloud = !!CLOUD[row.provider]
+          const cred = credOf(props.credentials, row.provider)
+          const draft = (props.keyDrafts && props.keyDrafts[row.provider]) || ''
+          const badge = !cloud ? null
+            : (!cred.writable ? 'Set in environment' : (cred.configured ? 'Configured' : 'Not set'))
+          return React.createElement('div', { className: 'dts-entry', key: i },
+            React.createElement('div', { className: 'dts-row' },
+              React.createElement('select', {
+                value: row.provider, disabled: !props.writable,
+                onChange: (e) => change(i, { provider: e.target.value }),
+              }, PROVIDERS.map((p) => React.createElement('option', { key: p, value: p }, p))),
+              React.createElement('input', {
+                className: 'dts-model', value: row.model || '', disabled: !props.writable,
+                placeholder: MODEL_HINT[row.provider] || '', onChange: (e) => change(i, { model: e.target.value }),
+              }),
+              React.createElement('input', {
+                className: 'dts-model', value: row.voice || '', disabled: !props.writable,
+                placeholder: 'voice', onChange: (e) => change(i, { voice: e.target.value }),
+              }),
+              React.createElement('button', { type: 'button', className: 'dts-mini', title: 'Up', disabled: !props.writable, onClick: () => move(i, -1) }, '\u2191'),
+              React.createElement('button', { type: 'button', className: 'dts-mini', title: 'Down', disabled: !props.writable, onClick: () => move(i, 1) }, '\u2193'),
+              React.createElement('button', { type: 'button', className: 'dts-mini', title: 'Remove', disabled: !props.writable, onClick: () => remove(i) }, '\u00d7'),
+            ),
+            cloud ? React.createElement('div', { className: 'dts-row' },
+              React.createElement('input', {
+                className: 'dts-key', type: 'password', autoComplete: 'off',
+                value: draft, disabled: !props.writable || !cred.writable,
+                placeholder: cred.configured ? 'leave blank to keep' : 'paste API key',
+                onChange: (e) => props.onDraft(row.provider, e.target.value),
+                onBlur: (e) => props.onCommitKey(row.provider, e.target.value),
+              }),
+              React.createElement('span', { className: 'dts-badge' + (cred.configured ? ' dts-badge-on' : '') }, badge),
+              cred.configured && cred.writable ? React.createElement('button', {
+                type: 'button', className: 'dts-link', disabled: !props.writable,
+                onClick: () => props.onClearKey(row.provider),
+              }, 'Clear') : null,
+            ) : React.createElement('span', { className: 'dts-sub' }, 'Local / CLI provider — no API key'),
+            cloud && cred.ref ? React.createElement('span', { className: 'dts-sub' }, 'Stored as ' + cred.ref) : null,
+          )
+        }),
+        React.createElement('div', { className: 'dts-row' },
+          React.createElement('button', { type: 'button', className: 'dts-mini', title: 'Add provider', disabled: !props.writable, onClick: add }, '+'),
+          React.createElement('span', { className: 'dts-sub' }, 'Top to bottom is the fallback order. Cloud keys are saved to the host credentials store, never into plugin settings.'),
+        ),
+      )
+    }
+
+    function TtsSection() {
+      const [draft, setDraft] = React.useState(null)
+      const [credentials, setCredentials] = React.useState({})
+      const [keyDrafts, setKeyDrafts] = React.useState({})
+      const [saved, setSaved] = React.useState(false)
+      const [err, setErr] = React.useState('')
+      const writable = true
+
+      const applyPayload = (data) => {
+        const cfg = data && data.config ? data.config : {}
+        setDraft(JSON.parse(JSON.stringify(cfg)))
+        setCredentials(data && data.credentials ? data.credentials : {})
+        player.enabled = !!cfg.speakReplies
+      }
+
+      React.useEffect(() => {
+        let alive = true
+        fetch('/dsh-tts/config', { cache: 'no-store' }).then((res) => res.json()).then((data) => {
+          if (!alive) return
+          applyPayload(data)
+        }).catch((e) => { if (alive) setErr(String(e && e.message ? e.message : e)) })
+        return () => { alive = false }
+      }, [])
+
+      if (!draft) return React.createElement('div', { className: 'dts-wrap' }, 'Loading\u2026')
+
+      const setTop = (key, v) => setDraft((d) => Object.assign({}, d || {}, { [key]: v }))
+      const setDraftKey = (provider, value) => setKeyDrafts((d) => Object.assign({}, d, { [provider]: value }))
+
+      const commitKey = async (provider, raw) => {
+        const value = String(raw != null ? raw : ((keyDrafts && keyDrafts[provider]) || '')).trim()
+        if (!value) return
+        setErr('')
+        const res = await fetch('/dsh-tts/credential', {
+          method: 'PUT',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ provider: provider, value: value }),
+        })
+        const data = await res.json().catch(() => ({}))
+        if (!res.ok) throw new Error((data && data.error && data.error.message) || ('HTTP ' + res.status))
+        if (data && data.credentials) setCredentials(data.credentials)
+        setKeyDrafts((d) => Object.assign({}, d, { [provider]: '' }))
+      }
+
+      const clearKey = async (provider) => {
+        setErr('')
+        try {
+          const res = await fetch('/dsh-tts/credential', {
+            method: 'DELETE',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ provider: provider }),
+          })
+          const data = await res.json().catch(() => ({}))
+          if (!res.ok) throw new Error((data && data.error && data.error.message) || ('HTTP ' + res.status))
+          if (data && data.credentials) setCredentials(data.credentials)
+          setKeyDrafts((d) => Object.assign({}, d, { [provider]: '' }))
+        } catch (e) { setErr(String(e && e.message ? e.message : e)) }
+      }
+
+      const save = async () => {
+        setErr(''); setSaved(false)
+        if (!draft) return
+        try {
+          const keys = {}
+          Object.keys(keyDrafts || {}).forEach((p) => {
+            const v = String(keyDrafts[p] || '').trim()
+            if (v) keys[p] = v
+          })
+          const res = await fetch('/dsh-tts/config', {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(Object.assign({}, draft, { keys: keys })),
+          })
+          const data = await res.json().catch(() => ({}))
+          if (!res.ok) throw new Error((data && data.error && data.error.message) || ('HTTP ' + res.status))
+          applyPayload(data)
+          setKeyDrafts({})
+          setSaved(true); setTimeout(() => setSaved(false), 2000)
+        } catch (e) { setErr(String(e && e.message ? e.message : e)) }
+      }
+
+      const onCommitKey = (provider, raw) => {
+        commitKey(provider, raw).catch((e) => setErr(String(e && e.message ? e.message : e)))
+      }
+
+      const textField = (key, label, hint) => React.createElement('label', { className: 'dts-field' }, label,
+        React.createElement('input', {
+          value: draft && draft[key] !== undefined ? draft[key] : '', disabled: !writable,
+          onChange: (e) => setTop(key, e.target.value),
+        }),
+        React.createElement('span', { className: 'dts-sub' }, hint))
+
+      return React.createElement('div', { className: 'dts-wrap' },
+        React.createElement('div', { className: 'dts-block' },
+          React.createElement('div', { className: 'dts-h' }, 'Speech'),
+          React.createElement('label', { className: 'dts-row' },
+            React.createElement('input', {
+              type: 'checkbox', checked: !!(draft && draft.speakReplies), disabled: !writable,
+              onChange: (e) => setTop('speakReplies', e.target.checked),
+            }),
+            React.createElement('span', null, 'Speak agent replies'),
+          ),
+          React.createElement('div', { className: 'dts-sub' },
+            'When on, each finished reply is synthesized on the host and played in this browser. Audio is not sent back to the model.'),
+        ),
+        React.createElement('div', { className: 'dts-block' },
+          React.createElement('div', { className: 'dts-h' }, 'Provider chain'),
+          React.createElement('div', { className: 'dts-sub' },
+            'Pick a provider, paste its API key, and Save (or leave the key field). The key is written to the host credentials store immediately. The browser never reads it back.'),
+          React.createElement(ChainEditor, {
+            value: draft && draft.chain ? draft.chain : [], writable: writable,
+            credentials: credentials, keyDrafts: keyDrafts,
+            onChange: (v) => setTop('chain', v),
+            onDraft: setDraftKey,
+            onCommitKey: onCommitKey,
+            onClearKey: clearKey,
+          }),
+        ),
+        React.createElement('div', { className: 'dts-block' },
+          React.createElement('div', { className: 'dts-h' }, 'General'),
+          textField('language', 'Language', 'Hint for voices that need a locale (eSpeak, Azure SSML).'),
+          textField('piperModel', 'Piper model path', 'Absolute path to an ONNX model. Leave empty to skip Piper.'),
+          textField('piperBin', 'Piper binary', 'Looked up in PATH unless absolute.'),
+          textField('espeakBin', 'eSpeak binary', 'Usually espeak-ng.'),
+          textField('edgeBin', 'edge-tts binary', 'Python CLI from the edge-tts package.'),
+          textField('azureRegion', 'Azure region', 'Required for the azure provider, e.g. eastus.'),
+        ),
+        React.createElement('div', { className: 'dts-row' },
+          React.createElement('button', { type: 'button', className: 'dts-save', disabled: !writable, onClick: save }, 'Save'),
+          saved ? React.createElement('span', { className: 'dts-ok' }, 'Saved') : null,
+          err ? React.createElement('span', { className: 'dts-bad' }, err) : null,
+        ),
+      )
+    }
+
+    function registerSettings(ctx) {
+      ctx.slots.inject('settings.section', () => ctx.slots.register(
+        { name: 'settings.section', id: '@goodandready/dsh-tts', order: 32, label: () => 'Speech', inject: () => ({ ctx: ctx }) },
+        TtsSection,
+      ))
+    }
+
+    exports.inject = ['slots']
+    exports.apply = function apply(ctx) {
+      registerSettings(ctx)
+      setInterval(pollPending, 1000)
+    }
+    return module.exports
+  },
+})