@goodandready/dsh-voice 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-voice 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,110 @@
+# dsh-voice
+
+Voice input for the DeepSeek Harness Web GUI, in two modes, each with its own
+provider fallback chain.
+
+**Dictation** — press the mic, talk, and the text lands in the composer as you
+go: speech is cut into phrases on silence and each phrase is transcribed on its
+own. Press again to stop; sending stays in your hands.
+
+**Voice message** — press the wave button, record, press again. The transcript
+is inserted and sent to the agent after a short cancel window.
+
+Both modes fall back across providers, so one outage or rate limit does not
+lose your recording. API keys never reach the browser: audio is posted to the
+plugin's own route and the host talks to the providers.
+
+## Install
+
+```bash
+# From npm:
+dsh plugin --profile web add @goodandready/dsh-voice
+
+# Locally from a checkout:
+dsh plugin --profile web add file:/path/to/dsh-voice
+```
+
+Restart the Web UI afterwards, then hard-refresh the browser.
+
+## Providers
+
+| Key | Service | Default model | Credential |
+|---|---|---|---|
+| `deepgram` | Deepgram | `nova-2` | `DEEPGRAM_API_KEY` |
+| `groq` | Groq | `whisper-large-v3-turbo` | `GROQ_API_KEY` |
+| `hf` | HuggingFace Inference | `openai/whisper-large-v3` | `HF_TOKEN` |
+| `local-whisper` | local whisper.cpp server | model given at server start | none, fully offline |
+
+Keys are read through the DSH credentials service (Settings → Credentials, or
+`$DSH_HOME/.credentials.yaml`), falling back to the process environment. A
+provider without a key is skipped, not fatal.
+
+## Configure (Web GUI)
+
+Settings → **Голос** (Voice) has three blocks:
+
+- **Dictation** — fallback chain (provider + optional model per row, order is
+  the order of attempts), language, and the silence threshold that ends a
+  phrase (`vadSilenceMs`, default 700 ms).
+- **Voice message** — its own independent chain, language, and the cancel
+  window before the message is sent (`autoSendMs`, default 4000 ms).
+- **General** — local whisper endpoint, binary, model, autostart.
+
+Speed matters for dictation and accuracy for messages, which is why the chains
+are separate: a sensible pair is Deepgram → Groq → local for dictation and
+Groq → HuggingFace → local for messages.
+
+## Local whisper.cpp
+
+The local provider needs a running [whisper.cpp](https://github.com/ggerganov/whisper.cpp)
+server:
+
+```bash
+whisper-server -m /path/to/ggml-medium-q8_0.bin --host 127.0.0.1 --port 8001
+```
+
+Set `whisperModel` (and `whisperBin` if it is not in `PATH`) and the plugin
+launches the server itself when `autoStart` is on. While `whisperModel` is
+empty, autostart stays off.
+
+**ffmpeg is required for this provider.** whisper.cpp accepts WAV only and
+rejects the webm/opus the browser records, so the host converts each recording
+to 16 kHz mono WAV before forwarding it. Point `ffmpegBin` at your binary if it
+is not in `PATH`.
+
+## Tool
+
+The plugin also registers `transcribe_audio(file_path, language?)` for the
+agent, using the voice-message chain. Useful for recordings and interviews that
+are already files on disk.
+
+## Routes
+
+| Route | Purpose |
+|---|---|
+| `POST /dsh-voice/transcribe` | `{dataBase64, mimeType, mode}` → `{ok, text, provider, tookMs}` |
+| `GET /dsh-voice/status` | whisper server state and the effective chains |
+
+## Structure
+
+```
+lib/index.js       host: config, routes, transcribe_audio, whisper autostart
+lib/providers.js   the four providers, pure functions (network injected)
+lib/chain.js       fallback walk over a chain
+lib/wav.js         webm/opus → WAV 16 kHz mono via ffmpeg
+lib/client.js      browser: composer buttons, recording, settings page
+test/              node --test units for the chain and the providers
+```
+
+Run the tests with `npm test` (no dependencies, Node's built-in runner).
+
+## Requirements
+
+- DeepSeek Harness with the Web GUI
+- Node 20+
+- ffmpeg, for the local whisper provider
+- a microphone reachable from the browser (HTTPS or localhost)
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,19 @@
+# dsh-voice bundle layer: applied automatically when the package is installed
+# as a profile bundle (package.json declares dsh.bundle.patch).
+#
+# `name` must stay the full npm package name: the client-modules registry
+# resolves the browser bundle by the loader entry name, so a shortened name
+# leaves the UI half silently out of window.__DSH_BOOT__.
+#
+# Override any field in the profile's own cordis.patch.yml, e.g. to point the
+# plugin at a local whisper.cpp build:
+#
+#   - id: dsh-voice
+#     config:
+#       whisperBin: /opt/whisper.cpp/build/bin/whisper-server
+#       whisperModel: /opt/whisper.cpp/models/ggml-medium-q8_0.bin
+#
+- insert:
+    - id: dsh-voice
+      name: '@goodandready/dsh-voice'
+      config: {}

package/lib/chain.js

@@ -0,0 +1,30 @@
+// Перебор цепочки провайдеров с фоллбеком. Без сети и без cordis — чистая
+// функция, чтобы поведение при отказах можно было проверить юнит-тестом.
+
+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?, text?, reason?}>>}
+ * @returns {Promise<{provider: string, text: string, tookMs: number}>}
+ */
+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) {
+        return { provider: out.provider || key, text: out.text, 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,604 @@
+// dsh-voice — клиентская половина (браузер).
+//
+// Две кнопки в conversation.input.right:
+//   микрофон — диктовка: речь режется по паузам, каждый кусок распознаётся и
+//              дописывается в строку ввода; отправка остаётся за пользователем;
+//   волна    — голосовое: одна запись целиком, после распознавания текст
+//              уходит агенту по истечении окна отмены.
+//
+// Полоска записи живёт в conversation.input.dock, страница настроек — в
+// settings.section.
+
+window.__ModuleLoader__.load({
+  id: '@goodandready/dsh-voice',
+  factory: (require) => {
+    var module = { exports: {} }
+    var exports = module.exports
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
+    let React = require('react')
+
+    const NS = 'dsh-voice'
+
+    // ------------------------------------------------------------------ css
+    const CSS =
+      '.dvo-btn{display:flex;align-items:center;justify-content:center;width:30px;height:30px;border-radius:50%;border:1px solid var(--dsw-alias-border-l1);background:transparent;color:var(--dsw-alias-label-secondary);cursor:pointer;padding:0;box-sizing:border-box}' +
+      '.dvo-btn:hover{color:var(--dsw-alias-label-primary);border-color:var(--dsw-alias-border-l2)}' +
+      '.dvo-btn[data-err="1"]{color:var(--dsw-alias-state-error-primary);border-color:var(--dsw-alias-state-error-primary)}' +
+      '.dvo-pill{display:flex;align-items:center;gap:10px;height:52px;border-radius:26px;background:var(--dsw-alias-bg-layer-1);border:1px solid var(--dsw-alias-border-l1);padding:0 14px;width:100%;max-width:720px;margin:0 auto;box-shadow:0 8px 24px rgba(0,0,0,.18);box-sizing:border-box}' +
+      '.dvo-pbtn{display:flex;align-items:center;justify-content:center;width:34px;height:34px;border-radius:50%;cursor:pointer;padding:0;flex:none;box-sizing:border-box;border:1px solid var(--dsw-alias-border-l2);background:transparent;color:var(--dsw-alias-label-primary)}' +
+      '.dvo-pbtn:hover{background:var(--dsw-alias-bg-layer-2)}' +
+      '.dvo-wave{flex:1;height:40px;width:100%;color:var(--dsw-alias-label-primary)}' +
+      '.dvo-status{display:flex;align-items:center;gap:8px;color:var(--dsw-alias-label-secondary);font-size:13px;flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}' +
+      '.dvo-err{color:var(--dsw-alias-state-error-primary)}' +
+      '.dvo-count{font-variant-numeric:tabular-nums;font-size:13px;color:var(--dsw-alias-label-secondary)}' +
+      '.dvo-spin{animation:dvo-spin 1s linear infinite}' +
+      '@keyframes dvo-spin{from{transform:rotate(0)}to{transform:rotate(360deg)}}'
+    const cssId = 'dsh-voice/client.module.css'
+    if (typeof document !== 'undefined' && !document.querySelector('style[data-plugin-css="' + cssId + '"]')) {
+      const tag = document.createElement('style')
+      tag.textContent = CSS
+      tag.setAttribute('data-plugin', 'dsh-voice')
+      tag.dataset.pluginCss = cssId
+      document.head.appendChild(tag)
+    }
+
+    // ---------------------------------------------------------------- store
+    const voice = {
+      phase: 'idle',      // idle | recording | processing | pending | error
+      mode: 'dictation',  // dictation | message
+      error: '',
+      rec: null,
+      levels: [],
+      pending: null,      // {text, leftMs} — окно отмены режима message
+      inputActions: null,
+      input: null,
+      settings: { vadSilenceMs: 700, autoSendMs: 4000 },
+      listeners: new Set(),
+      notify() { this.listeners.forEach((l) => l()) },
+      set(patch) { Object.assign(this, patch); this.notify() },
+      subscribe(l) { this.listeners.add(l); return () => this.listeners.delete(l) },
+    }
+
+    function useVoice() {
+      const [, force] = React.useReducer((x) => x + 1, 0)
+      React.useEffect(() => voice.subscribe(force), [])
+      return voice
+    }
+
+    // ---------------------------------------------------------------- icons
+    const ic = { width: 18, height: 18, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 2, strokeLinecap: 'round', strokeLinejoin: 'round' }
+    const micIcon = () => React.createElement('svg', ic,
+      React.createElement('path', { d: 'M12 1a3 3 0 0 0-3 3v8a3 3 0 0 0 6 0V4a3 3 0 0 0-3-3z' }),
+      React.createElement('path', { d: 'M19 10v2a7 7 0 0 1-14 0v-2' }),
+      React.createElement('line', { x1: 12, y1: 19, x2: 12, y2: 23 }))
+    const waveIcon = () => React.createElement('svg', ic,
+      React.createElement('line', { x1: 4, y1: 10, x2: 4, y2: 14 }),
+      React.createElement('line', { x1: 8, y1: 7, x2: 8, y2: 17 }),
+      React.createElement('line', { x1: 12, y1: 4, x2: 12, y2: 20 }),
+      React.createElement('line', { x1: 16, y1: 7, x2: 16, y2: 17 }),
+      React.createElement('line', { x1: 20, y1: 10, x2: 20, y2: 14 }))
+    const xIcon = () => React.createElement('svg', ic,
+      React.createElement('line', { x1: 18, y1: 6, x2: 6, y2: 18 }),
+      React.createElement('line', { x1: 6, y1: 6, x2: 18, y2: 18 }))
+    const stopIcon = () => React.createElement('svg', ic,
+      React.createElement('rect', { x: 7, y: 7, width: 10, height: 10, rx: 2.5, fill: 'currentColor', stroke: 'none' }))
+    const spinIcon = () => React.createElement('svg', Object.assign({}, ic, { className: 'dvo-spin' }),
+      React.createElement('path', { d: 'M21 12a9 9 0 1 1-6.219-8.56' }))
+    const warnIcon = () => React.createElement('svg', ic,
+      React.createElement('path', { d: 'M10.29 3.86L1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z' }),
+      React.createElement('line', { x1: 12, y1: 9, x2: 12, y2: 13 }),
+      React.createElement('line', { x1: 12, y1: 17, x2: 12.01, y2: 17 }))
+
+    // ------------------------------------------------------------ transport
+    function blobToBase64(blob) {
+      return new Promise((resolve, reject) => {
+        if (typeof FileReader === 'undefined') { reject(new Error('FileReader not supported')); return }
+        const fr = new FileReader()
+        fr.onload = () => { const s = String(fr.result || ''); resolve(s.indexOf(',') >= 0 ? s.slice(s.indexOf(',') + 1) : s) }
+        fr.onerror = () => reject(new Error('failed to read audio'))
+        fr.readAsDataURL(blob)
+      })
+    }
+
+    async function sendAudio(blob, mime, mode) {
+      const dataBase64 = await blobToBase64(blob)
+      const res = await fetch('/dsh-voice/transcribe', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ dataBase64, mimeType: mime, mode }),
+      })
+      let parsed = null
+      try { parsed = await res.json() } catch (e) { /* не json */ }
+      if (!res.ok || !parsed || !parsed.ok) {
+        throw new Error((parsed && parsed.error && parsed.error.message) || `HTTP ${res.status}`)
+      }
+      return String(parsed.text || '').trim()
+    }
+
+    function appendDraft(text) {
+      const actions = voice.inputActions
+      if (!actions || typeof actions.setDraft !== 'function') {
+        voice.set({ phase: 'error', error: 'Композер недоступен' })
+        return
+      }
+      const draft = voice.input && typeof voice.input.draft === 'string' ? voice.input.draft : ''
+      actions.setDraft(draft ? draft + ' ' + text : text)
+    }
+
+    // ------------------------------------------------------------ recording
+    function teardown(rec) {
+      if (!rec) return
+      try { rec.stream.getTracks().forEach((t) => t.stop()) } catch (e) { /* уже остановлен */ }
+      if (rec.audioCtx) { try { rec.audioCtx.close() } catch (e) { /* уже закрыт */ } }
+    }
+
+    function waitStop(recorder) {
+      return new Promise((resolve) => recorder.addEventListener('stop', resolve, { once: true }))
+    }
+
+    async function openMic(mode) {
+      if (typeof navigator === 'undefined' || !navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
+        throw new Error('Микрофон недоступен: нужен HTTPS или localhost')
+      }
+      if (typeof MediaRecorder === 'undefined') throw new Error('MediaRecorder не поддерживается браузером')
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: { channelCount: 1, echoCancellation: true, noiseSuppression: true },
+      })
+      let mimeType = 'audio/webm;codecs=opus'
+      if (!MediaRecorder.isTypeSupported(mimeType)) mimeType = ''
+      const recorder = mimeType ? new MediaRecorder(stream, { mimeType }) : new MediaRecorder(stream)
+      const rec = {
+        recorder, stream, mode,
+        chunks: [],
+        mime: mimeType || recorder.mimeType || 'audio/webm',
+        audioCtx: null, analyser: null,
+        cutting: false, closing: false,
+        silenceMs: 0, hadSpeech: false,
+      }
+      recorder.ondataavailable = (e) => { if (e.data && e.data.size > 0) rec.chunks.push(e.data) }
+      const AC = typeof AudioContext !== 'undefined' ? AudioContext
+        : (typeof webkitAudioContext !== 'undefined' ? webkitAudioContext : null)
+      if (AC) {
+        rec.audioCtx = new AC()
+        const src = rec.audioCtx.createMediaStreamSource(stream)
+        rec.analyser = rec.audioCtx.createAnalyser()
+        rec.analyser.fftSize = 128
+        src.connect(rec.analyser)
+      }
+      // Без timeslice: только тогда каждый stop() даёт самостоятельный webm-файл.
+      recorder.start()
+      return rec
+    }
+
+    function currentLevel(rec) {
+      if (!rec || !rec.analyser) return 0
+      const data = new Uint8Array(rec.analyser.frequencyBinCount)
+      rec.analyser.getByteFrequencyData(data)
+      let sum = 0
+      for (let i = 0; i < data.length; i++) sum += data[i]
+      return Math.min(1, (sum / data.length / 255) * 2.2)
+    }
+
+    // Режет текущую фразу: останавливает рекордер, отправляет готовый файл и
+    // немедленно начинает новую запись тем же рекордером.
+    function cutPhrase() {
+      const rec = voice.rec
+      if (!rec || rec.cutting || rec.closing) return
+      rec.cutting = true
+      const stopped = waitStop(rec.recorder)
+      try { rec.recorder.stop() } catch (e) { /* уже остановлен */ }
+      stopped.then(async () => {
+        const blob = new Blob(rec.chunks, { type: rec.mime })
+        rec.chunks = []
+        rec.silenceMs = 0
+        rec.hadSpeech = false
+        if (!rec.closing) {
+          try { rec.recorder.start() } catch (e) { /* поток закрылся */ }
+        }
+        rec.cutting = false
+        if (blob.size < 1200) return       // слишком короткий кусок — это не речь
+        try {
+          const text = await sendAudio(blob, rec.mime, 'dictation')
+          if (text) appendDraft(text)
+        } catch (e) {
+          voice.set({ error: String(e && e.message ? e.message : e) })
+        }
+      })
+    }
+
+    function startRecording(mode) {
+      if (voice.phase !== 'idle' && voice.phase !== 'error') return
+      voice.set({ phase: 'recording', mode, error: '', levels: [] })
+      openMic(mode)
+        .then((rec) => { voice.rec = rec; voice.notify() })
+        .catch((err) => voice.set({ phase: 'error', error: String(err && err.message ? err.message : err), rec: null }))
+    }
+
+    function startDictation() { startRecording('dictation') }
+    function startMessage() { startRecording('message') }
+
+    function cancelCurrent() {
+      const rec = voice.rec
+      voice.pending = null
+      if (!rec) { voice.set({ phase: 'idle', error: '' }); return }
+      rec.closing = true
+      const stopped = waitStop(rec.recorder)
+      try { rec.recorder.stop() } catch (e) { /* уже остановлен */ }
+      stopped.then(() => { teardown(rec); voice.rec = null; voice.set({ phase: 'idle', error: '' }) })
+    }
+
+    // Останов по второму нажатию: диктовка досылает хвост, голосовое —
+    // отправляет всю запись и открывает окно отмены.
+    function stopCurrent() {
+      const rec = voice.rec
+      if (!rec || rec.closing) return
+      rec.closing = true
+      const mode = rec.mode
+      const stopped = waitStop(rec.recorder)
+      try { rec.recorder.stop() } catch (e) { /* уже остановлен */ }
+      stopped.then(async () => {
+        const blob = new Blob(rec.chunks, { type: rec.mime })
+        teardown(rec)
+        voice.rec = null
+        if (blob.size < 1200) { voice.set({ phase: 'idle' }); return }
+        voice.set({ phase: 'processing' })
+        try {
+          const text = await sendAudio(blob, rec.mime, mode)
+          if (!text) { voice.set({ phase: 'error', error: 'Речь не распознана' }); return }
+          appendDraft(text)
+          if (mode === 'message') {
+            voice.set({ phase: 'pending', pending: { text: text, leftMs: voice.settings.autoSendMs } })
+          } else {
+            voice.set({ phase: 'idle' })
+          }
+        } catch (e) {
+          voice.set({ phase: 'error', error: String(e && e.message ? e.message : e) })
+        }
+      })
+    }
+
+    function submitPending() {
+      voice.pending = null
+      voice.set({ phase: 'idle' })
+      const actions = voice.inputActions
+      if (actions && typeof actions.submit === 'function') {
+        setTimeout(() => { try { actions.submit() } catch (e) { /* композер занят */ } }, 0)
+      }
+    }
+
+    function keepPending() {
+      voice.pending = null
+      voice.set({ phase: 'idle' })
+    }
+
+    // ----------------------------------------------------------- components
+    function VoiceButtons(props) {
+      const v = useVoice()
+      voice.inputActions = props.inputActions
+      voice.input = props.input
+      if (v.phase !== 'idle' && v.phase !== 'error') return null
+      const err = v.phase === 'error'
+      return React.createElement(React.Fragment, null,
+        React.createElement('button', {
+          type: 'button', className: 'dvo-btn', 'data-err': err ? '1' : '0',
+          title: err ? v.error : 'Голосовой набор', onClick: startDictation,
+        }, micIcon()),
+        React.createElement('button', {
+          type: 'button', className: 'dvo-btn', 'data-err': err ? '1' : '0',
+          title: err ? v.error : 'Голосовое сообщение', onClick: startMessage,
+        }, waveIcon()),
+      )
+    }
+
+    function RecordPill(props) {
+      const v = useVoice()
+      const canvasRef = React.useRef(null)
+      voice.inputActions = props.inputActions
+      voice.input = props.input
+      const ctx = props.ctx
+
+      // VAD: копим тишину и режем фразу, когда пауза превысила порог.
+      React.useEffect(() => {
+        if (v.phase !== 'recording') return
+        const tick = 50
+        const dispose = ctx.interval(() => {
+          const rec = voice.rec
+          if (!rec) return
+          const level = currentLevel(rec)
+          voice.levels.push(level)
+          if (voice.levels.length > 150) voice.levels.shift()
+          if (level > 0.06) { rec.hadSpeech = true; rec.silenceMs = 0 }
+          else if (rec.hadSpeech) rec.silenceMs += tick
+          if (rec.mode === 'dictation' && rec.hadSpeech && rec.silenceMs >= voice.settings.vadSilenceMs) {
+            cutPhrase()
+          }
+        }, tick)
+        return () => dispose()
+      }, [v.phase])
+
+      // Осциллограмма.
+      React.useEffect(() => {
+        if (v.phase !== 'recording') return
+        const dispose = ctx.interval(() => {
+          const canvas = canvasRef.current
+          if (!canvas) return
+          const g = canvas.getContext('2d')
+          const w = canvas.width, h = canvas.height
+          g.clearRect(0, 0, w, h)
+          if (!voice.waveColor) {
+            try { voice.waveColor = getComputedStyle(canvas).color || '#fff' } catch (e) { voice.waveColor = '#fff' }
+          }
+          const levels = voice.levels
+          const midY = h / 2
+          for (let i = 0; i < levels.length && i * 7 < w; i++) {
+            const level = levels[levels.length - 1 - i]
+            const age = i / levels.length
+            const x = w - 10 - i * 7
+            const hh = Math.max(2.5, level * (h - 6) * 0.5 * (1 - age * 0.35))
+            g.globalAlpha = 1 - age * 0.75
+            g.fillStyle = voice.waveColor
+            g.fillRect(x, midY - hh, 3.5, hh * 2)
+          }
+          g.globalAlpha = 1
+        }, 50)
+        return () => dispose()
+      }, [v.phase])
+
+      // Окно отмены режима message.
+      React.useEffect(() => {
+        if (v.phase !== 'pending') return
+        const tick = 100
+        const dispose = ctx.interval(() => {
+          const p = voice.pending
+          if (!p) return
+          p.leftMs -= tick
+          if (p.leftMs <= 0) { submitPending(); return }
+          voice.notify()
+        }, tick)
+        return () => dispose()
+      }, [v.phase])
+
+      if (v.phase === 'idle') return null
+
+      if (v.phase === 'recording') {
+        const hint = v.mode === 'dictation' ? 'Диктовка — текст дописывается в строку' : 'Запись голосового'
+        return React.createElement('div', { className: 'dvo-pill' },
+          React.createElement('button', { type: 'button', className: 'dvo-pbtn', title: 'Отмена', onClick: cancelCurrent }, xIcon()),
+          React.createElement('canvas', { className: 'dvo-wave', ref: canvasRef, width: 720, height: 40 }),
+          React.createElement('span', { className: 'dvo-status' }, hint),
+          React.createElement('button', { type: 'button', className: 'dvo-pbtn', title: 'Стоп', onClick: stopCurrent }, stopIcon()),
+        )
+      }
+
+      if (v.phase === 'processing') {
+        return React.createElement('div', { className: 'dvo-pill' },
+          React.createElement('span', { className: 'dvo-status' }, spinIcon(), 'Распознаю…'))
+      }
+
+      if (v.phase === 'pending') {
+        const left = Math.max(0, Math.ceil((voice.pending ? voice.pending.leftMs : 0) / 1000))
+        return React.createElement('div', { className: 'dvo-pill' },
+          React.createElement('span', { className: 'dvo-status' }, 'Отправляю агенту через'),
+          React.createElement('span', { className: 'dvo-count' }, left + ' с'),
+          React.createElement('button', { type: 'button', className: 'dvo-pbtn', title: 'Отменить отправку', onClick: keepPending }, xIcon()),
+        )
+      }
+
+      return React.createElement('div', { className: 'dvo-pill' },
+        React.createElement('span', { className: 'dvo-status dvo-err' }, warnIcon(), v.error),
+        React.createElement('button', { type: 'button', className: 'dvo-pbtn', title: 'Скрыть', onClick: () => voice.set({ phase: 'idle', error: '' }) }, xIcon()),
+      )
+    }
+
+    // --------------------------------------------------------------- slots
+    function registerComposer(ctx) {
+      ctx.slots.inject('conversation.input.right', () => ctx.slots.register(
+        { name: 'conversation.input.right', id: '@goodandready/dsh-voice', order: 6, label: () => 'Голос' },
+        (props) => React.createElement(VoiceButtons, { input: props.input, inputActions: props.inputActions }),
+      ))
+      ctx.slots.inject('conversation.input.dock', () => ctx.slots.register(
+        { name: 'conversation.input.dock', id: 'dsh-voice-rec', order: 0, label: () => 'Запись голоса' },
+        (props) => React.createElement(RecordPill, { input: props.input, inputActions: props.inputActions, ctx: ctx }),
+      ))
+    }
+
+    // ------------------------------------------------------- settings page
+    const PROVIDERS = ['deepgram', 'groq', 'hf', 'local-whisper']
+    const MODEL_HINT = {
+      deepgram: 'nova-2', groq: 'whisper-large-v3-turbo',
+      hf: 'openai/whisper-large-v3', 'local-whisper': 'задаётся при запуске сервера',
+    }
+    const LANGS = ['auto', 'ru', 'en', 'uk', 'de']
+
+    const SET_CSS =
+      '.dvs-wrap{display:flex;flex-direction:column;gap:22px;padding:4px 0;max-width:720px}' +
+      '.dvs-block{display:flex;flex-direction:column;gap:10px}' +
+      '.dvs-h{font-size:14px;font-weight:600;color:var(--dsw-alias-label-primary)}' +
+      '.dvs-sub{font-size:12px;color:var(--dsw-alias-label-secondary)}' +
+      '.dvs-row{display:flex;gap:8px;align-items:center}' +
+      '.dvs-row select,.dvs-row input{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}' +
+      '.dvs-row .dvs-model{flex:1}' +
+      '.dvs-field{display:flex;flex-direction:column;gap:4px;font-size:12px;color:var(--dsw-alias-label-secondary)}' +
+      '.dvs-field input,.dvs-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}' +
+      '.dvs-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}' +
+      '.dvs-save{background:var(--dsw-alias-brand-primary);color:#fff;border:none;border-radius:6px;padding:7px 14px;font-size:13px;cursor:pointer}' +
+      '.dvs-ok{font-size:12px;color:var(--dsw-alias-state-success-primary)}' +
+      '.dvs-bad{font-size:12px;color:var(--dsw-alias-state-error-primary)}'
+    const setCssId = 'dsh-voice/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-voice')
+      tag.dataset.pluginCss = setCssId
+      document.head.appendChild(tag)
+    }
+
+    // Редактор одной цепочки: строки «провайдер + модель» с перестановкой.
+    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: 'local-whisper', model: '' }]))
+
+      return React.createElement('div', { className: 'dvs-block' },
+        rows.map((row, i) => React.createElement('div', { className: 'dvs-row', key: i },
+          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: 'dvs-model', value: row.model || '', disabled: !props.writable,
+            placeholder: MODEL_HINT[row.provider] || '', onChange: (e) => change(i, { model: e.target.value }),
+          }),
+          React.createElement('button', { type: 'button', className: 'dvs-mini', title: 'Выше', disabled: !props.writable, onClick: () => move(i, -1) }, '↑'),
+          React.createElement('button', { type: 'button', className: 'dvs-mini', title: 'Ниже', disabled: !props.writable, onClick: () => move(i, 1) }, '↓'),
+          React.createElement('button', { type: 'button', className: 'dvs-mini', title: 'Убрать', disabled: !props.writable, onClick: () => remove(i) }, '×'),
+        )),
+        React.createElement('div', { className: 'dvs-row' },
+          React.createElement('button', { type: 'button', className: 'dvs-mini', title: 'Добавить провайдера', disabled: !props.writable, onClick: add }, '+'),
+          React.createElement('span', { className: 'dvs-sub' }, 'Порядок сверху вниз — порядок попыток'),
+        ),
+      )
+    }
+
+    function VoiceSection(props) {
+      const ctx = props.ctx
+      const scope = ctx.settingsScope.bind({ namespace: NS })
+      const [snap, setSnap] = React.useState(null)
+      const [draft, setDraft] = React.useState(null)
+      const [saved, setSaved] = React.useState(false)
+      const [err, setErr] = React.useState('')
+
+      React.useEffect(() => {
+        let alive = true
+        const render = () => { if (alive) setSnap(scope.getSnapshot()) }
+        render()
+        const off = scope.subscribe(render)
+        return () => { alive = false; off() }
+      }, [])
+
+      const value = snap && snap.value ? snap.value : {}
+      const writable = snap ? snap.writable !== false : false
+      React.useEffect(() => { if (snap && draft === null) setDraft(JSON.parse(JSON.stringify(value))) }, [snap, draft, value])
+      // Клиент должен знать порог VAD и окно отмены — они живут в тех же настройках.
+      React.useEffect(() => {
+        if (!snap) return
+        voice.settings = {
+          vadSilenceMs: Number(value && value.dictation && value.dictation.vadSilenceMs) || 700,
+          autoSendMs: Number(value && value.message && value.message.autoSendMs) || 4000,
+        }
+      }, [snap])
+
+      if (!snap) return React.createElement('div', { className: 'dvs-wrap' }, 'Загрузка…')
+
+      const setIn = (mode, key, v) => setDraft((d) => {
+        const next = JSON.parse(JSON.stringify(d || {}))
+        next[mode] = next[mode] || {}
+        next[mode][key] = v
+        return next
+      })
+      const setTop = (key, v) => setDraft((d) => Object.assign({}, d || {}, { [key]: v }))
+
+      const save = async () => {
+        setErr(''); setSaved(false)
+        if (!draft) return
+        try {
+          for (const k of Object.keys(draft)) await scope.set(k, draft[k])
+          voice.settings = {
+            vadSilenceMs: Number(draft.dictation && draft.dictation.vadSilenceMs) || 700,
+            autoSendMs: Number(draft.message && draft.message.autoSendMs) || 4000,
+          }
+          setSaved(true); setTimeout(() => setSaved(false), 2000)
+        } catch (e) { setErr(String(e && e.message ? e.message : e)) }
+      }
+
+      const modeVal = (mode, key, fallback) => {
+        const m = draft && draft[mode]
+        return m && m[key] !== undefined ? m[key] : fallback
+      }
+
+      const langField = (mode) => React.createElement('label', { className: 'dvs-field' }, 'Язык',
+        React.createElement('select', {
+          value: modeVal(mode, 'language', 'ru'), disabled: !writable,
+          onChange: (e) => setIn(mode, 'language', e.target.value),
+        }, LANGS.map((o) => React.createElement('option', { key: o, value: o }, o))))
+
+      const numField = (mode, key, label, hint) => React.createElement('label', { className: 'dvs-field' }, label,
+        React.createElement('input', {
+          type: 'number', value: modeVal(mode, key, ''), disabled: !writable,
+          onChange: (e) => setIn(mode, key, Number(e.target.value)),
+        }),
+        React.createElement('span', { className: 'dvs-sub' }, hint))
+
+      const textField = (key, label, hint) => React.createElement('label', { className: 'dvs-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: 'dvs-sub' }, hint))
+
+      return React.createElement('div', { className: 'dvs-wrap' },
+        React.createElement('div', { className: 'dvs-block' },
+          React.createElement('div', { className: 'dvs-h' }, 'Голосовой набор'),
+          React.createElement('div', { className: 'dvs-sub' }, 'Речь режется по паузам, текст дописывается в строку ввода.'),
+          React.createElement(ChainEditor, {
+            value: draft && draft.dictation ? draft.dictation.chain : [], writable: writable,
+            onChange: (v) => setIn('dictation', 'chain', v),
+          }),
+          langField('dictation'),
+          numField('dictation', 'vadSilenceMs', 'Пауза до конца фразы, мс', 'Меньше — чаще куски и быстрее текст, но выше риск обрезать слово'),
+        ),
+        React.createElement('div', { className: 'dvs-block' },
+          React.createElement('div', { className: 'dvs-h' }, 'Голосовое сообщение'),
+          React.createElement('div', { className: 'dvs-sub' }, 'Одна запись целиком, после распознавания уходит агенту.'),
+          React.createElement(ChainEditor, {
+            value: draft && draft.message ? draft.message.chain : [], writable: writable,
+            onChange: (v) => setIn('message', 'chain', v),
+          }),
+          langField('message'),
+          numField('message', 'autoSendMs', 'Окно отмены, мс', 'Сколько времени можно отменить автоматическую отправку'),
+        ),
+        React.createElement('div', { className: 'dvs-block' },
+          React.createElement('div', { className: 'dvs-h' }, 'Общее'),
+          textField('whisperUrl', 'Локальный whisper: endpoint', 'POST /inference сервера whisper.cpp'),
+          textField('whisperBin', 'Локальный whisper: бинарь', 'используется при автозапуске'),
+          textField('whisperModel', 'Локальный whisper: модель', 'используется при автозапуске'),
+          React.createElement('label', { className: 'dvs-field' }, 'Автозапуск локального whisper',
+            React.createElement('input', {
+              type: 'checkbox', checked: !!(draft && draft.autoStart), disabled: !writable,
+              onChange: (e) => setTop('autoStart', e.target.checked),
+            })),
+        ),
+        React.createElement('div', { className: 'dvs-row' },
+          React.createElement('button', { type: 'button', className: 'dvs-save', disabled: !writable, onClick: save }, 'Сохранить'),
+          saved ? React.createElement('span', { className: 'dvs-ok' }, 'Сохранено ✓') : null,
+          err ? React.createElement('span', { className: 'dvs-bad' }, err) : null,
+        ),
+      )
+    }
+
+    function registerSettings(ctx) {
+      ctx.slots.inject('settings.section', () => ctx.slots.register(
+        { name: 'settings.section', id: '@goodandready/dsh-voice', order: 30, label: () => 'Голос', inject: () => ({ ctx: ctx }) },
+        VoiceSection,
+      ))
+    }
+
+    exports.inject = ['timer', 'slots', 'settingsScope']
+    exports.apply = function apply(ctx) {
+      registerComposer(ctx)
+      registerSettings(ctx)
+    }
+    return module.exports
+  },
+})

package/lib/index.js

@@ -0,0 +1,266 @@
+// dsh-voice — хост-половина.
+//
+// Два режима ввода голосом, у каждого своя цепочка провайдеров:
+//   dictation — браузер режет речь по паузам и шлёт куски, текст дописывается
+//               в строку ввода;
+//   message   — одна запись целиком, текст уходит агенту после окна отмены.
+//
+// Роуты:
+//   POST /dsh-voice/transcribe  {dataBase64, mimeType, mode} -> {ok, text, provider, tookMs}
+//   GET  /dsh-voice/status      -> {ok, whisperRunning, modes}
+//
+// Ключи провайдеров читаются на хосте через ctx.credentials и в браузер не
+// попадают.
+
+import z from '@deepseek-ai/schemastery'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { credentialRef } from '@deepseek-ai/dsh-credentials'
+import { readFile, stat } from 'node:fs/promises'
+import path from 'node:path'
+import { runChain } from './chain.js'
+import { makeProviders, PROVIDER_KEYS, DEFAULT_MODELS } from './providers.js'
+import { toWav16k } from './wav.js'
+
+export const name = 'dsh-voice'
+export const inject = ['tools', 'credentials', 'webServer', 'shell']
+
+const ChainEntry = z.object({
+  provider: z.string().default('local-whisper')
+    .description(`Provider key. One of: ${PROVIDER_KEYS.join(', ')}.`),
+  model: z.string().default('')
+    .description('Model override. Empty means the provider default.'),
+})
+
+export const Config = z.object({
+  dictation: z.object({
+    chain: z.array(ChainEntry)
+      .default([{ provider: 'deepgram', model: '' }, { provider: 'groq', model: '' }, { provider: 'local-whisper', model: '' }])
+      .description('Fallback chain for dictation. Speed matters more than accuracy here.'),
+    language: z.string().default('ru'),
+    vadSilenceMs: z.number().default(700)
+      .description('Silence longer than this ends a phrase and sends the chunk.'),
+  }).default({}),
+  message: z.object({
+    chain: z.array(ChainEntry)
+      .default([{ provider: 'groq', model: '' }, { provider: 'hf', model: '' }, { provider: 'local-whisper', model: '' }])
+      .description('Fallback chain for voice messages. Accuracy matters more than speed.'),
+    language: z.string().default('ru'),
+    autoSendMs: z.number().default(4000)
+      .description('Cancel window before the recognized text is sent to the agent.'),
+  }).default({}),
+  deepgramKeyEnv: z.string().default('DEEPGRAM_API_KEY'),
+  groqKeyEnv: z.string().default('GROQ_API_KEY'),
+  hfTokenEnv: z.string().default('HF_TOKEN'),
+  whisperUrl: z.string().default('http://127.0.0.1:8001/inference'),
+  whisperBin: z.string().default('whisper-server')
+    .description('whisper.cpp server binary, looked up in PATH unless an absolute path is given.'),
+  whisperModel: z.string().default('')
+    .description('Absolute path to the ggml model. Autostart stays off while this is empty; '
+      + 'point it at your own model file to let the plugin launch whisper.cpp itself.'),
+  autoStart: z.boolean().default(true)
+    .description('Launch the local whisper.cpp server on activation if the port is free. '
+      + 'Requires whisperModel to be set.'),
+  ffmpegBin: z.string().default('ffmpeg')
+    .description('ffmpeg used to convert browser webm/opus into the WAV that whisper.cpp requires.'),
+  timeoutMs: z.number().default(120000),
+  maxFileBytes: z.number().default(25 * 1024 * 1024),
+})
+
+const MIME_BY_EXT = {
+  '.wav': 'audio/wav', '.mp3': 'audio/mpeg', '.m4a': 'audio/mp4', '.mp4': 'audio/mp4',
+  '.ogg': 'audio/ogg', '.oga': 'audio/ogg', '.flac': 'audio/flac', '.webm': 'audio/webm', '.aac': 'audio/aac',
+}
+
+function writeJson(res, code, body) {
+  try {
+    res.writeHead(code, { 'Content-Type': 'application/json', 'Cache-Control': 'no-store' })
+    res.end(JSON.stringify(body))
+  } catch { /* сокет мог закрыться */ }
+}
+
+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)
+  })
+}
+
+export function apply(ctx, config) {
+  let child = null
+
+  async function resolveKey(ref) {
+    try {
+      const resolved = await ctx.credentials.resolve(credentialRef(ref))
+      if (resolved && resolved.value) return resolved.value
+    } catch { /* падаем в окружение */ }
+    return process.env[ref] || ''
+  }
+
+  async function whisperAlive() {
+    try {
+      const controller = new AbortController()
+      const t = setTimeout(() => controller.abort(), 2000)
+      const res = await fetch(config.whisperUrl.split('/inference')[0] + '/', { signal: controller.signal })
+      clearTimeout(t)
+      return res.ok
+    } catch { return false }
+  }
+
+  async function startWhisper() {
+    if (!config.autoStart) return false
+    // Без пути к модели запускать нечего: пакет не знает, где она лежит у
+    // конкретного пользователя, и молча стартовать чужой бинарь не должен.
+    if (!config.whisperModel) return false
+    if (await whisperAlive()) return true
+    try {
+      const spec = ctx.shell.resolve({
+        command: `${JSON.stringify(config.whisperBin)} -m ${JSON.stringify(config.whisperModel)}`
+          + ` --host 127.0.0.1 --port 8001 -t 8 -p 1 -l ${config.dictation.language}`,
+        timeoutMs: 0,
+        stdoutMaxBytes: 4 * 1024 * 1024,
+      })
+      child = ctx.shell.start(spec)
+      for (let i = 0; i < 20; i++) {
+        await new Promise((r) => setTimeout(r, 500))
+        if (await whisperAlive()) return true
+      }
+      return false
+    } catch { return false }
+  }
+
+  startWhisper().catch(() => {})
+
+  // Общий путь распознавания: собрать провайдеров по цепочке режима и пройти её.
+  async function transcribe(modeCfg, bytes, mime, signal) {
+    const models = {}
+    const order = []
+    for (const entry of Array.isArray(modeCfg.chain) ? modeCfg.chain : []) {
+      if (!PROVIDER_KEYS.includes(entry.provider)) continue
+      order.push(entry.provider)
+      models[entry.provider] = entry.model || DEFAULT_MODELS[entry.provider]
+    }
+    const providers = makeProviders(
+      { resolveKey, fetchImpl: fetch, cfg: config, toWav: (b) => toWav16k(b, config.ffmpegBin) },
+      { bytes, mime, lang: modeCfg.language, signal, models },
+    )
+    return runChain(order, providers)
+  }
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-voice/status',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') { writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } }); return }
+      writeJson(res, 200, {
+        ok: true,
+        whisperRunning: await whisperAlive(),
+        modes: {
+          dictation: { chain: config.dictation.chain, language: config.dictation.language, vadSilenceMs: config.dictation.vadSilenceMs },
+          message: { chain: config.message.chain, language: config.message.language, autoSendMs: config.message.autoSendMs },
+        },
+      })
+    },
+  }), 'dsh-voice: /status route')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-voice/transcribe',
+    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, config.maxFileBytes + 1024 * 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 dataBase64 = typeof payload.dataBase64 === 'string' ? payload.dataBase64 : ''
+      if (!dataBase64) { writeJson(res, 400, { ok: false, error: { code: 'no-audio', message: 'no audio data' } }); return }
+      const mime = typeof payload.mimeType === 'string' && payload.mimeType ? payload.mimeType : 'audio/webm'
+      const modeCfg = payload.mode === 'message' ? config.message : config.dictation
+
+      let bytes
+      try { bytes = Buffer.from(dataBase64, 'base64') } catch { bytes = null }
+      if (!bytes || bytes.length === 0) {
+        writeJson(res, 400, { ok: false, error: { code: 'decode', message: 'failed to decode audio' } }); return
+      }
+      if (bytes.length > config.maxFileBytes) {
+        writeJson(res, 413, { ok: false, error: { code: 'too-large', message: `audio is ${bytes.length} bytes, max ${config.maxFileBytes}` } }); return
+      }
+
+      // Локальный whisper в цепочке — поднимаем сервер заранее, иначе первый
+      // же чанк уйдёт в отказ, пока сервер стартует.
+      if ((modeCfg.chain || []).some((e) => e.provider === 'local-whisper') && !(await whisperAlive())) {
+        await startWhisper()
+      }
+
+      const controller = new AbortController()
+      const timer = setTimeout(() => controller.abort(), config.timeoutMs)
+      try {
+        const out = await transcribe(modeCfg, bytes, mime, controller.signal)
+        writeJson(res, 200, { ok: true, text: out.text, provider: out.provider, tookMs: out.tookMs })
+      } catch (e) {
+        writeJson(res, 502, { ok: false, error: { code: 'chain', message: String(e && e.message || e) } })
+      } finally {
+        clearTimeout(timer)
+      }
+    },
+  }), 'dsh-voice: /transcribe route')
+
+  ctx.tools.register(
+    defineTool({
+      name: 'transcribe_audio',
+      description:
+        'Recognize speech in an audio file and return the transcript as text. '
+        + 'Uses the voice-message fallback chain from the dsh-voice settings, so a single '
+        + 'provider outage or rate limit does not fail the request. '
+        + 'Use for voice messages, recordings, interviews.',
+      parameters: {
+        file_path: { type: 'string', required: true, description: 'Absolute path to the audio file (wav, mp3, m4a, ogg, flac, webm).' },
+        language: { type: 'string', description: `Recognition language code. Default: ${config.message.language}.` },
+      },
+      output: {
+        schema: {
+          type: 'object',
+          additionalProperties: false,
+          properties: { provider: { type: 'string' }, text: { type: 'string' }, tookMs: { type: 'integer' } },
+        },
+        render(args, value) {
+          const body = value.text.length > 4000
+            ? `${value.text.slice(0, 4000)}\n…[truncated ${value.text.length} chars]`
+            : value.text
+          return [{ type: 'text', text: `transcribe_audio (${value.provider}, ${value.tookMs}ms):\n${body}` }]
+        },
+      },
+      isConcurrencySafe: () => false,
+      timeoutMs: config.timeoutMs * 3 + 5000,
+      async execute(args, exec) {
+        const filePath = String(args.file_path || '').trim()
+        if (!filePath) throw new Error('transcribe_audio: file_path is required')
+        const info = await stat(filePath).catch(() => null)
+        if (!info) throw new Error(`transcribe_audio: file not found: ${filePath}`)
+        if (info.size > config.maxFileBytes) {
+          throw new Error(`transcribe_audio: file too large (${info.size} bytes, max ${config.maxFileBytes})`)
+        }
+        if (info.size < 100) throw new Error('transcribe_audio: file is empty or too small')
+        const mime = MIME_BY_EXT[path.extname(filePath).toLowerCase()] || 'audio/wav'
+        const bytes = await readFile(filePath)
+        const modeCfg = { ...config.message, language: String(args.language || config.message.language) }
+        return transcribe(modeCfg, bytes, mime, exec.signal)
+      },
+    }),
+  )
+
+  ctx.effect(() => () => {
+    if (child) { try { child.kill && child.kill() } catch { /* уже мёртв */ } }
+  }, 'dsh-voice: stop whisper child')
+}

package/lib/providers.js

@@ -0,0 +1,118 @@
+// Четыре провайдера распознавания речи. Чистые функции: сеть приходит
+// параметром (fetchImpl), ключи — через resolveKey, поэтому всё проверяется
+// без реальных запросов.
+
+export const PROVIDER_KEYS = ['deepgram', 'groq', 'hf', 'local-whisper']
+
+export const DEFAULT_MODELS = {
+  deepgram: 'nova-2',
+  groq: 'whisper-large-v3-turbo',
+  hf: 'openai/whisper-large-v3',
+  'local-whisper': '',
+}
+
+function pickModel(models, key) {
+  const chosen = models && typeof models[key] === 'string' ? models[key].trim() : ''
+  return chosen || DEFAULT_MODELS[key]
+}
+
+function fileName(mime) {
+  if (mime.includes('wav')) return 'audio.wav'
+  if (mime.includes('ogg')) return 'audio.ogg'
+  if (mime.includes('mp4')) return 'audio.m4a'
+  return 'audio.webm'
+}
+
+export function makeProviders(deps, req) {
+  const { resolveKey, fetchImpl, cfg } = deps
+  const { bytes, mime, lang, signal, models } = req
+
+  async function deepgram() {
+    const key = await resolveKey(cfg.deepgramKeyEnv)
+    if (!key) return { ok: false, provider: 'deepgram', reason: `no ${cfg.deepgramKeyEnv}` }
+    const model = pickModel(models, 'deepgram')
+    const url = `https://api.deepgram.com/v1/listen?model=${encodeURIComponent(model)}`
+      + `&language=${encodeURIComponent(lang)}&smart_format=true`
+    const res = await fetchImpl(url, {
+      method: 'POST',
+      headers: { authorization: `Token ${key}`, 'content-type': mime },
+      body: bytes,
+      signal,
+    })
+    if (!res.ok) throw new Error(`Deepgram HTTP ${res.status}`)
+    const data = await res.json()
+    const text = (data?.results?.channels?.[0]?.alternatives?.[0]?.transcript || '').trim()
+    return { ok: text.length > 0, provider: 'deepgram', text, reason: text ? '' : 'empty transcript' }
+  }
+
+  async function groq() {
+    const key = await resolveKey(cfg.groqKeyEnv)
+    if (!key) return { ok: false, provider: 'groq', reason: `no ${cfg.groqKeyEnv}` }
+    const form = new FormData()
+    form.append('file', new Blob([bytes], { type: mime }), fileName(mime))
+    form.append('model', pickModel(models, 'groq'))
+    form.append('language', lang)
+    form.append('response_format', 'json')
+    const res = await fetchImpl('https://api.groq.com/openai/v1/audio/transcriptions', {
+      method: 'POST',
+      headers: { authorization: `Bearer ${key}` },
+      body: form,
+      signal,
+    })
+    if (!res.ok) throw new Error(`Groq HTTP ${res.status}`)
+    const data = await res.json()
+    const text = (data?.text || '').trim()
+    return { ok: text.length > 0, provider: 'groq', text, reason: text ? '' : 'empty transcript' }
+  }
+
+  async function hf() {
+    const token = await resolveKey(cfg.hfTokenEnv)
+    if (!token) return { ok: false, provider: 'hf', reason: `no ${cfg.hfTokenEnv}` }
+    const model = pickModel(models, 'hf')
+    const res = await fetchImpl(`https://router.huggingface.co/hf-inference/models/${model}`, {
+      method: 'POST',
+      headers: { authorization: `Bearer ${token}`, 'content-type': mime, 'x-wait-for-model': 'true' },
+      body: bytes,
+      signal,
+    })
+    if (!res.ok) throw new Error(`HF HTTP ${res.status}`)
+    const data = await res.json()
+    const text = (data?.text || '').trim()
+    return { ok: text.length > 0, provider: 'hf', text, reason: text ? '' : 'empty transcript' }
+  }
+
+  // whisper.cpp принимает только WAV — на webm/opus из браузера его сервер
+  // отвечает "Invalid request". Перегоняем, если формат не WAV.
+  async function localWhisper() {
+    let sendBytes = bytes
+    let sendMime = mime
+    if (!mime.includes('wav')) {
+      if (typeof deps.toWav !== 'function') {
+        return { ok: false, provider: 'local-whisper', reason: 'local whisper needs WAV, no converter configured' }
+      }
+      try {
+        sendBytes = await deps.toWav(bytes)
+        sendMime = 'audio/wav'
+      } catch (e) {
+        return { ok: false, provider: 'local-whisper', reason: `local whisper: ${String(e && e.message || e)}` }
+      }
+    }
+    const form = new FormData()
+    form.append('file', new Blob([sendBytes], { type: sendMime }), fileName(sendMime))
+    form.append('language', lang)
+    form.append('response_format', 'json')
+    const res = await fetchImpl(cfg.whisperUrl, { method: 'POST', body: form, signal })
+    // whisper.cpp отвечает 400 с JSON-телом на внутренних сбоях (например, не
+    // смог декодировать аудио) — читаем причину, а не бросаем исключение.
+    if (!res.ok) {
+      let detail = `HTTP ${res.status}`
+      try { const e = await res.json(); if (e?.error) detail = e.error } catch { /* тело не json */ }
+      return { ok: false, provider: 'local-whisper', reason: `local whisper: ${detail}` }
+    }
+    const data = await res.json()
+    const text = (data?.text || '').trim()
+    return { ok: text.length > 0, provider: 'local-whisper', text, reason: text ? '' : 'empty transcript' }
+  }
+
+  return { deepgram, groq, hf, 'local-whisper': localWhisper }
+}

package/lib/wav.js

@@ -0,0 +1,39 @@
+// Перегон произвольного аудио в WAV 16 кГц моно.
+//
+// Локальный whisper.cpp принимает только WAV: на webm/opus, который пишет
+// браузер, его сервер отвечает "Invalid request". API-провайдеры webm едят
+// как есть, поэтому конвертация нужна ровно для локальной ноги цепочки.
+
+import { spawn } from 'node:child_process'
+
+/**
+ * @param bytes {Buffer|Uint8Array} исходное аудио в любом контейнере
+ * @param ffmpegBin {string} путь к ffmpeg
+ * @returns {Promise<Buffer>} WAV 16 кГц моно
+ */
+export function toWav16k(bytes, ffmpegBin = 'ffmpeg') {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(ffmpegBin, [
+      '-hide_banner', '-loglevel', 'error',
+      '-i', 'pipe:0',
+      '-ar', '16000', '-ac', '1',
+      '-f', 'wav', 'pipe:1',
+    ])
+    const out = []
+    const err = []
+    proc.stdout.on('data', (c) => out.push(c))
+    proc.stderr.on('data', (c) => err.push(c))
+    proc.on('error', (e) => reject(new Error(`ffmpeg unavailable: ${e.message}`)))
+    proc.on('close', (code) => {
+      if (code !== 0) {
+        reject(new Error(`ffmpeg exit ${code}: ${Buffer.concat(err).toString('utf8').slice(0, 200)}`))
+        return
+      }
+      const wav = Buffer.concat(out)
+      if (wav.length < 64) { reject(new Error('ffmpeg produced empty output')); return }
+      resolve(wav)
+    })
+    proc.stdin.on('error', () => { /* ffmpeg закрыл вход раньше — код возврата всё расскажет */ })
+    proc.stdin.end(Buffer.from(bytes))
+  })
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@goodandready/dsh-voice",
+  "version": "0.3.0",
+  "description": "Voice input for DeepSeek Harness: dictation chunked by pauses and voice messages, each with its own provider fallback chain (Deepgram, Groq, HuggingFace, local whisper.cpp).",
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "voice",
+    "stt",
+    "dictation",
+    "whisper",
+    "deepgram",
+    "groq"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GooDAnDReaDY/dsh-voice.git"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-voice",
+  "bugs": {
+    "url": "https://github.com/GooDAnDReaDY/dsh-voice/issues"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}