@goodandready/dsh-voice 0.9.47 → 0.9.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/providers.js CHANGED
@@ -1,24 +1,42 @@
1
- // Speech recognition providers: built-ins plus custom ones from settings.
2
- // Pure functions: network arrives as fetchImpl, keys via resolveKey, so
3
- // everything is testable without real requests.
1
+ // Speech recognition providers: built-ins plus custom ones from settings (#306).
2
+ // Uses Strategy pattern and ProviderRegistry in lib/provider-registry.js.
4
3
 
5
- // 'browser' is listed for chain validation only: recognition runs in the
6
- // page and audio never reaches the host. Without this key a ['browser','groq']
7
- // chain would break on the host instead of falling through to groq.
8
- export const PROVIDER_KEYS = ['browser', 'browser-webgpu', 'deepgram', 'groq', 'hf', 'local-whisper', 'sensevoice']
4
+ import { readErrorDetail, readHttpError, safeJson, isAutoLang, fileName, chatAudioFormat } from './provider-http.js'
5
+ import {
6
+ SpeechToTextProvider,
7
+ BrowserStubProvider,
8
+ DeepgramProvider,
9
+ GroqProvider,
10
+ HuggingFaceProvider,
11
+ LocalWhisperProvider,
12
+ SenseVoiceProvider,
13
+ OpenAICompatibleProvider,
14
+ ProviderRegistry,
15
+ createDefaultProviderRegistry,
16
+ } from './provider-registry.js'
17
+
18
+ export {
19
+ readErrorDetail,
20
+ readHttpError,
21
+ safeJson,
22
+ isAutoLang,
23
+ fileName,
24
+ chatAudioFormat,
25
+ SpeechToTextProvider,
26
+ BrowserStubProvider,
27
+ DeepgramProvider,
28
+ GroqProvider,
29
+ HuggingFaceProvider,
30
+ LocalWhisperProvider,
31
+ SenseVoiceProvider,
32
+ OpenAICompatibleProvider,
33
+ ProviderRegistry,
34
+ createDefaultProviderRegistry,
35
+ }
9
36
 
10
- // Custom providers use one of two templates because OpenAI-compatible APIs
11
- // diverged: OpenRouter has no /audio/transcriptions and recognizes via chat.
37
+ export const PROVIDER_KEYS = ['browser', 'browser-webgpu', 'deepgram', 'groq', 'hf', 'local-whisper', 'sensevoice']
12
38
  export const CUSTOM_TEMPLATES = ['openai-transcriptions', 'openai-chat-audio']
13
39
 
14
- // Presets: the same as a custom provider with address, model and key name
15
- // already filled in. Only the key itself is required.
16
- //
17
- // Each URL answers 401 without a key, so the path exists. The model is a
18
- // reasonable starting point and can be overridden per chain row.
19
- //
20
- // A custom provider with the same name fully replaces a preset: presets are
21
- // prefilled forms, not special engines.
22
40
  export const PRESET_PROVIDERS = {
23
41
  openai: {
24
42
  template: 'openai-transcriptions',
@@ -50,7 +68,6 @@ export const PRESET_PROVIDERS = {
50
68
  model: 'voxtral-mini-latest',
51
69
  keyEnv: 'MISTRAL_API_KEY',
52
70
  },
53
- // OpenRouter has no /audio/transcriptions at all — chat only.
54
71
  openrouter: {
55
72
  template: 'openai-chat-audio',
56
73
  baseURL: 'https://openrouter.ai/api/v1',
@@ -60,17 +77,8 @@ export const PRESET_PROVIDERS = {
60
77
  }
61
78
 
62
79
  export const PRESET_KEYS = Object.keys(PRESET_PROVIDERS)
63
-
64
- /** All names usable in a chain without declaring a custom provider. */
65
80
  export const KNOWN_KEYS = PROVIDER_KEYS.concat(PRESET_KEYS)
66
81
 
67
- const CHAT_AUDIO_PROMPT =
68
- 'Transcribe the audio verbatim. Reply with the transcript text only, '
69
- + 'without comments, quotes or formatting.'
70
-
71
- import { readErrorDetail, readHttpError, safeJson, isAutoLang, fileName, chatAudioFormat } from './provider-http.js'
72
- export { readErrorDetail, readHttpError, safeJson, isAutoLang, fileName, chatAudioFormat }
73
-
74
82
  export const DEFAULT_MODELS = {
75
83
  deepgram: 'nova-2',
76
84
  groq: 'whisper-large-v3-turbo',
@@ -79,305 +87,8 @@ export const DEFAULT_MODELS = {
79
87
  sensevoice: 'SenseVoiceSmall',
80
88
  }
81
89
 
82
- function pickModel(models, key) {
83
- const chosen = models && typeof models[key] === 'string' ? models[key].trim() : ''
84
- return chosen || DEFAULT_MODELS[key]
85
- }
86
-
90
+ export const defaultProviderRegistry = createDefaultProviderRegistry(PRESET_PROVIDERS)
87
91
 
88
92
  export function makeProviders(deps, req) {
89
- const { resolveKey, fetchImpl, cfg } = deps
90
- const { bytes, mime, lang, signal, models, promptText, keywords } = req
91
- const vocab = Array.isArray(req.vocabulary)
92
- ? req.vocabulary.map((w) => String(w || '').trim()).filter(Boolean).join(', ')
93
- : ''
94
- const effectivePrompt = (typeof promptText === 'string' && promptText.trim()) ? promptText.trim() : vocab
95
- const effectiveKeywords = (typeof keywords === 'string' && keywords.trim()) ? keywords.trim() : vocab
96
-
97
- async function deepgram() {
98
- const key = await resolveKey(cfg.deepgramKeyEnv)
99
- if (!key) return { ok: false, provider: 'deepgram', reason: `no ${cfg.deepgramKeyEnv}` }
100
- const model = pickModel(models, 'deepgram')
101
- const base = String(cfg.deepgramBaseUrl || 'https://api.deepgram.com').replace(/\/+$/, '')
102
- const url = `${base}/v1/listen?model=${encodeURIComponent(model)}`
103
- + (!isAutoLang(lang) ? `&language=${encodeURIComponent(lang)}` : '')
104
- + (effectiveKeywords ? `&keywords=${encodeURIComponent(effectiveKeywords)}` : '')
105
- + '&smart_format=true'
106
- const res = await fetchImpl(url, {
107
- method: 'POST',
108
- headers: { authorization: `Token ${key}`, 'content-type': mime },
109
- body: bytes,
110
- signal,
111
- keepalive: true,
112
- })
113
- if (!res.ok) throw await readHttpError(res, 'Deepgram', 'deepgram')
114
- let data
115
- try { data = await safeJson(res, 'Deepgram') } catch (e) {
116
- return { ok: false, provider: 'deepgram', reason: e.message }
117
- }
118
- const text = (data?.results?.channels?.[0]?.alternatives?.[0]?.transcript || '').trim()
119
- return { ok: text.length > 0, provider: 'deepgram', text, reason: text ? '' : 'empty transcript' }
120
- }
121
-
122
- async function groq() {
123
- const key = await resolveKey(cfg.groqKeyEnv)
124
- if (!key) return { ok: false, provider: 'groq', reason: `no ${cfg.groqKeyEnv}` }
125
- const form = new FormData()
126
- form.append('file', new Blob([bytes], { type: mime }), fileName(mime))
127
- form.append('model', pickModel(models, 'groq'))
128
- if (!isAutoLang(lang)) form.append('language', lang)
129
- if (effectivePrompt) form.append('prompt', effectivePrompt)
130
- form.append('response_format', 'json')
131
- const res = await fetchImpl('https://api.groq.com/openai/v1/audio/transcriptions', {
132
- method: 'POST',
133
- headers: { authorization: `Bearer ${key}` },
134
- body: form,
135
- signal,
136
- keepalive: true,
137
- })
138
- if (!res.ok) throw await readHttpError(res, 'Groq', 'groq')
139
- let data
140
- try { data = await safeJson(res, 'Groq') } catch (e) {
141
- return { ok: false, provider: 'groq', reason: e.message }
142
- }
143
- const text = (data?.text || '').trim()
144
- return { ok: text.length > 0, provider: 'groq', text, reason: text ? '' : 'empty transcript' }
145
- }
146
-
147
- async function hf() {
148
- const token = await resolveKey(cfg.hfTokenEnv)
149
- if (!token) return { ok: false, provider: 'hf', reason: `no ${cfg.hfTokenEnv}` }
150
- const model = pickModel(models, 'hf')
151
- const res = await fetchImpl(`https://router.huggingface.co/hf-inference/models/${model}`, {
152
- method: 'POST',
153
- headers: { authorization: `Bearer ${token}`, 'content-type': mime, 'x-wait-for-model': 'true' },
154
- body: bytes,
155
- signal,
156
- keepalive: true,
157
- })
158
- if (!res.ok) throw await readHttpError(res, 'HF', 'hf')
159
- let data
160
- try { data = await safeJson(res, 'HF') } catch (e) {
161
- return { ok: false, provider: 'hf', reason: e.message }
162
- }
163
- const text = (data?.text || '').trim()
164
- return { ok: text.length > 0, provider: 'hf', text, reason: text ? '' : 'empty transcript' }
165
- }
166
-
167
- // whisper.cpp accepts WAV only — browser webm/opus gets "Invalid request".
168
- // Convert when the format is not WAV.
169
- async function localWhisper() {
170
- let sendBytes = bytes
171
- let sendMime = mime
172
- if (!mime.includes('wav')) {
173
- if (typeof deps.toWav !== 'function') {
174
- return { ok: false, provider: 'local-whisper', reason: 'local whisper needs WAV, no converter configured' }
175
- }
176
- try {
177
- sendBytes = await deps.toWav(bytes, signal)
178
- sendMime = 'audio/wav'
179
- } catch (e) {
180
- return { ok: false, provider: 'local-whisper', reason: `local whisper: ${String(e && e.message || e)}` }
181
- }
182
- }
183
- const form = new FormData()
184
- form.append('file', new Blob([sendBytes], { type: sendMime }), fileName(sendMime))
185
- // Unlike OpenAI-compatible APIs, whisper.cpp inherits its server's default
186
- // language when the form omits this field (normally `en`). Send `auto`
187
- // explicitly so every request detects the spoken language.
188
- form.append('language', isAutoLang(lang) ? 'auto' : lang)
189
- // Also override a server started with --translate: this plugin always needs
190
- // a transcript in the spoken language, never Whisper's English translation.
191
- form.append('translate', 'false')
192
- if (effectivePrompt) form.append('prompt', effectivePrompt)
193
- form.append('response_format', 'json')
194
- const res = await fetchImpl(cfg.whisperUrl, { method: 'POST', body: form, signal })
195
- // whisper.cpp returns 400 with a JSON body on internal failures (e.g. decode
196
- // errors) — read the reason instead of throwing.
197
- if (!res.ok) {
198
- let detail = `HTTP ${res.status}`
199
- try { const e = await res.json(); if (e?.error) detail = e.error } catch { /* body is not json */ }
200
- return { ok: false, provider: 'local-whisper', reason: `local whisper: ${detail}` }
201
- }
202
- let data
203
- try { data = await safeJson(res, 'local whisper') } catch (e) {
204
- return { ok: false, provider: 'local-whisper', reason: e.message }
205
- }
206
- const text = (data?.text || '').trim()
207
- return { ok: text.length > 0, provider: 'local-whisper', text, reason: text ? '' : 'empty transcript' }
208
- }
209
-
210
- // SenseVoice-ONNX / Sherpa-ONNX: ultra-fast local recognition (~50-100ms).
211
- // Supports sherpa-onnx (/api/v1/asr) and OpenAI-compatible endpoints.
212
- async function sensevoice() {
213
- const url = String(cfg.sensevoiceUrl || 'http://127.0.0.1:6006/api/v1/asr').trim()
214
- let sendBytes = bytes
215
- let sendMime = mime
216
- if (!mime.includes('wav')) {
217
- if (typeof deps.toWav !== 'function') {
218
- return { ok: false, provider: 'sensevoice', reason: 'sensevoice needs WAV, no converter configured' }
219
- }
220
- try {
221
- sendBytes = await deps.toWav(bytes, signal)
222
- sendMime = 'audio/wav'
223
- } catch (e) {
224
- return { ok: false, provider: 'sensevoice', reason: `sensevoice: ${String(e && e.message || e)}` }
225
- }
226
- }
227
- const form = new FormData()
228
- form.append('file', new Blob([sendBytes], { type: sendMime }), fileName(sendMime))
229
- const isOpenAI = url.includes('/transcriptions')
230
- if (isOpenAI) {
231
- form.append('model', pickModel(models, 'sensevoice'))
232
- if (!isAutoLang(lang)) form.append('language', lang)
233
- if (effectivePrompt) form.append('prompt', effectivePrompt)
234
- form.append('response_format', 'json')
235
- }
236
-
237
- let res
238
- try {
239
- res = await fetchImpl(url, { method: 'POST', body: form, signal })
240
- } catch (e) {
241
- return { ok: false, provider: 'sensevoice', reason: `sensevoice: ${String(e && e.message || e)}` }
242
- }
243
-
244
- if (!res.ok) {
245
- let detail = `HTTP ${res.status}`
246
- try { const e = await res.json(); if (e?.error) detail = e.error } catch { /* body is not json */ }
247
- return { ok: false, provider: 'sensevoice', reason: `sensevoice: ${detail}` }
248
- }
249
-
250
- let data
251
- try {
252
- data = await res.json()
253
- } catch {
254
- return { ok: false, provider: 'sensevoice', reason: 'sensevoice: invalid json response' }
255
- }
256
-
257
- let text = String(data?.text || data?.transcript || '').trim()
258
- // Strip SenseVoice emotion/event tags (<|NEUTRAL|>, <|HAPPY|>, <|Speech|>, ...).
259
- text = text.replace(/<\|[^|>]+\|>/g, '').trim()
260
- return {
261
- ok: text.length > 0,
262
- provider: 'sensevoice',
263
- text,
264
- reason: text ? '' : 'empty transcript',
265
- }
266
- }
267
-
268
- // Custom provider. The chain key is its name, so the rest of the code
269
- // treats it like a built-in.
270
- function customProvider(spec) {
271
- const label = spec.key
272
- const base = String(spec.baseURL || '').replace(/\/+$/, '')
273
- const model = pickModel(models, label) || spec.model
274
-
275
- async function auth() {
276
- if (!spec.keyEnv) return {}
277
- const key = await resolveKey(spec.keyEnv)
278
- if (!key) return null
279
- return { authorization: `Bearer ${key}` }
280
- }
281
-
282
- async function viaTranscriptions(headers) {
283
- const form = new FormData()
284
- form.append('file', new Blob([bytes], { type: mime }), fileName(mime))
285
- form.append('model', model)
286
- if (lang && lang !== 'auto') form.append('language', lang)
287
- if (effectivePrompt) form.append('prompt', effectivePrompt)
288
- form.append('response_format', 'json')
289
- const res = await fetchImpl(`${base}/audio/transcriptions`, {
290
- method: 'POST', headers, body: form, signal,
291
- })
292
- if (!res.ok) throw await readHttpError(res, label, spec.key)
293
- const data = await safeJson(res, label)
294
- return (data?.text || '').trim()
295
- }
296
-
297
- async function viaChatAudio(headers) {
298
- let sendBytes = bytes
299
- let format = chatAudioFormat(mime)
300
- if (!format) {
301
- if (typeof deps.toWav !== 'function') {
302
- throw new Error(`${label}: chat template needs wav or mp3, unsupported format ${mime}`)
303
- }
304
- sendBytes = await deps.toWav(bytes, signal)
305
- format = 'wav'
306
- }
307
- const ask = (spec.prompt || CHAT_AUDIO_PROMPT)
308
- + (effectivePrompt ? ` Vocabulary hints (spell these correctly): ${effectivePrompt}.` : '')
309
- + (lang && lang !== 'auto' ? ` The audio language is ${lang}.` : '')
310
- const res = await fetchImpl(`${base}/chat/completions`, {
311
- method: 'POST',
312
- headers: { ...headers, 'content-type': 'application/json' },
313
- body: JSON.stringify({
314
- model,
315
- messages: [{
316
- role: 'user',
317
- content: [
318
- { type: 'text', text: ask },
319
- { type: 'input_audio', input_audio: { data: Buffer.from(sendBytes).toString('base64'), format } },
320
- ],
321
- }],
322
- }),
323
- signal,
324
- })
325
- if (!res.ok) throw await readHttpError(res, label, spec.key)
326
- const data = await safeJson(res, label)
327
- return String(data?.choices?.[0]?.message?.content || '').trim()
328
- }
329
-
330
- return async function run() {
331
- if (!base) return { ok: false, provider: label, reason: `${label}: no baseURL` }
332
- if (!model) return { ok: false, provider: label, reason: `${label}: no model` }
333
- const headers = await auth()
334
- if (headers === null) return { ok: false, provider: label, reason: `no ${spec.keyEnv}` }
335
- let text
336
- try {
337
- text = spec.template === 'openai-chat-audio'
338
- ? await viaChatAudio(headers)
339
- : await viaTranscriptions(headers)
340
- } catch (e) {
341
- // One provider failure must not abort the chain — the chain decides
342
- // whether to continue or give up.
343
- return { ok: false, provider: label, reason: `${label}: ${String(e && e.message || e)}` }
344
- }
345
- return { ok: text.length > 0, provider: label, text, reason: text ? '' : 'empty transcript' }
346
- }
347
- }
348
-
349
- // If audio still reached the host with 'browser' or 'browser-webgpu' in the chain,
350
- // the client-side leg failed: fail clearly and move on.
351
- async function browser() {
352
- return {
353
- ok: false,
354
- provider: 'browser',
355
- reason: 'browser: recognition runs in the page, the host has no browser engine',
356
- }
357
- }
358
-
359
- async function browserWebGpu() {
360
- return {
361
- ok: false,
362
- provider: 'browser-webgpu',
363
- reason: 'browser-webgpu: recognition runs in the page via WebGPU/WASM, the host has no browser engine',
364
- }
365
- }
366
-
367
- const out = { browser, 'browser-webgpu': browserWebGpu, deepgram, groq, hf, 'local-whisper': localWhisper, sensevoice }
368
-
369
- // Presets: custom providers with the form pre-filled.
370
- for (const key of PRESET_KEYS) {
371
- if (out[key]) continue
372
- out[key] = customProvider({ ...PRESET_PROVIDERS[key], key })
373
- }
374
-
375
- for (const spec of Array.isArray(cfg.customProviders) ? cfg.customProviders : []) {
376
- const key = String(spec && spec.key || '').trim()
377
- // Do not override built-in engines: a typo would silently replace a working
378
- // provider in a chain. Presets may be overridden — that is their purpose.
379
- if (!key || PROVIDER_KEYS.includes(key)) continue
380
- out[key] = customProvider({ ...spec, key })
381
- }
382
- return out
93
+ return defaultProviderRegistry.buildRunners(deps, req)
383
94
  }
@@ -0,0 +1,10 @@
1
+ // Subsystem facade for local STT daemons (#304)
2
+ import { createLocalDaemons } from './local-daemon.js'
3
+
4
+ export function createServerDaemons({ live, ctx }) {
5
+ const daemons = createLocalDaemons({ live, ctx })
6
+ if (typeof ctx?.effect === 'function') {
7
+ ctx.effect(() => () => daemons.dispose(), 'dsh-voice: daemon cleanup')
8
+ }
9
+ return daemons
10
+ }
@@ -0,0 +1,59 @@
1
+ // HTTP and WebSocket route registration with explicit RouteDeps contract (#304)
2
+ import { registerHostRoutes } from './host-routes.js'
3
+ import { registerPluginUpdater } from './updater.js'
4
+ import { registerSensevoiceInstaller } from './sensevoice-installer.js'
5
+ import { registerConfigRoutes } from './config-routes.js'
6
+ import { sessionCommand } from './transcribe-core.js'
7
+ import { applyJargonDictionary, extractVoiceActions } from './normalize.js'
8
+ import { KNOWN_KEYS } from './providers.js'
9
+ import { BaseConfig } from './schema.js'
10
+
11
+ export function registerServerRoutes(ctx, deps) {
12
+ const {
13
+ NS = 'dsh-voice',
14
+ live,
15
+ daemons,
16
+ statsTracker,
17
+ transcribe,
18
+ polishText,
19
+ getSettingsService,
20
+ getScope,
21
+ updateConfig,
22
+ triggerAutostart,
23
+ manifestUrl = new URL('../package.json', import.meta.url),
24
+ } = deps
25
+
26
+ registerHostRoutes(ctx, {
27
+ live,
28
+ daemons,
29
+ statsTracker,
30
+ transcribe,
31
+ polishText,
32
+ sessionCommand,
33
+ extractVoiceActions,
34
+ applyJargonDictionary,
35
+ KNOWN_KEYS,
36
+ })
37
+
38
+ ctx.effect(() => registerPluginUpdater(ctx, {
39
+ endpoint: '/api/dsh-voice/update',
40
+ packageName: '@goodandready/dsh-voice',
41
+ manifestUrl,
42
+ }), 'dsh-voice: updater route')
43
+
44
+ ctx.effect(() => registerSensevoiceInstaller(ctx, {
45
+ liveConfig: live,
46
+ isAlive: daemons.sensevoiceAlive,
47
+ updateConfig,
48
+ startSensevoice: daemons.startSensevoice,
49
+ }), 'dsh-voice: sensevoice installer route')
50
+
51
+ ctx.effect(() => registerConfigRoutes(ctx, {
52
+ NS,
53
+ live,
54
+ getSettingsService,
55
+ getScope,
56
+ validateConfig: (val) => BaseConfig(structuredClone(val)),
57
+ triggerAutostart,
58
+ }), 'dsh-voice: config route')
59
+ }
@@ -0,0 +1,74 @@
1
+ // Subsystem for transcription pipeline, LLM polish, and agent tool registration (#304)
2
+ import { toWav16k } from './wav.js'
3
+ import { makeProviders, KNOWN_KEYS, DEFAULT_MODELS } from './providers.js'
4
+ import { runChain } from './chain.js'
5
+ import { buildTranscriptionPrompt, buildProviderOrder } from './transcribe-core.js'
6
+ import { registerTranscribeAudioTool } from './tool.js'
7
+ import { createPolishText } from './polish.js'
8
+ import { createUserMessage } from '@deepseek-ai/dsh-llm'
9
+ import { credentialRef } from '@deepseek-ai/dsh-credentials'
10
+
11
+ export function createSecretResolver(ctx) {
12
+ return async (ref) => {
13
+ if (!ref || typeof ref !== 'string') return ''
14
+ try {
15
+ const resolved = await ctx.credentials.resolve(credentialRef(ref))
16
+ return (typeof resolved === 'string' ? resolved : resolved?.value) || ''
17
+ } catch {
18
+ return ''
19
+ }
20
+ }
21
+ }
22
+
23
+ export function createServerPipeline({ ctx, live, statsTracker, fetchImpl = (...args) => fetch(...args) }) {
24
+ const resolveKey = createSecretResolver(ctx)
25
+
26
+ async function transcribe(modeCfg, bytes, mime, signal, contextWords) {
27
+ const cfg = live()
28
+ const customKeys = (Array.isArray(cfg.customProviders) ? cfg.customProviders : [])
29
+ .map((c) => String((c && c.key) || '').trim()).filter(Boolean)
30
+ const { order, models } = buildProviderOrder({
31
+ localOnly: !!cfg.localOnly,
32
+ chain: modeCfg.chain,
33
+ customKeys,
34
+ knownKeys: KNOWN_KEYS,
35
+ defaultModels: DEFAULT_MODELS,
36
+ })
37
+
38
+ const { promptText, keywords, vocabulary: vocab } = buildTranscriptionPrompt({
39
+ vocabulary: cfg.vocabulary,
40
+ contextWords: cfg.contextGlossary ? contextWords : [],
41
+ bilingualDeveloperPrompt: cfg.bilingualDeveloperPrompt !== false,
42
+ bilingualCustomPrompt: cfg.bilingualCustomPrompt || '',
43
+ language: modeCfg.language,
44
+ })
45
+
46
+ const providers = makeProviders(
47
+ { resolveKey, fetchImpl, cfg, toWav: (b, sig) => toWav16k(b, cfg.ffmpegBin, sig || signal) },
48
+ { bytes, mime, lang: modeCfg.language, signal, models, vocabulary: vocab, promptText, keywords },
49
+ )
50
+ return runChain(order, providers, statsTracker.record)
51
+ }
52
+
53
+ const polishText = createPolishText({
54
+ resolveKey,
55
+ fetchImpl,
56
+ getConfig: live,
57
+ llm: ctx.llm,
58
+ createUserMessage,
59
+ getAgentDefaultModel: () => (ctx.get && ctx.get('agentDefaultModel')?.currentSelection)
60
+ ? ctx.get('agentDefaultModel').currentSelection()
61
+ : null,
62
+ })
63
+
64
+ return { resolveKey, transcribe, polishText }
65
+ }
66
+
67
+ export function registerServerTools(ctx, { live, baseConfig, transcribe, polishText }) {
68
+ ctx.effect(() => registerTranscribeAudioTool(ctx, {
69
+ live,
70
+ baseConfig,
71
+ transcribe,
72
+ polishText,
73
+ }), 'dsh-voice: transcribe_audio tool')
74
+ }
@@ -0,0 +1,154 @@
1
+ // lib/supervisor.js — Process Supervisor and Lifecycle Finite State Machine (#310)
2
+
3
+ export const DAEMON_STATES = Object.freeze({
4
+ STOPPED: 'STOPPED',
5
+ STARTING: 'STARTING',
6
+ RUNNING: 'RUNNING',
7
+ DEGRADED: 'DEGRADED',
8
+ CRASHED: 'CRASHED',
9
+ RESTARTING: 'RESTARTING',
10
+ })
11
+
12
+ const VALID_TRANSITIONS = {
13
+ STOPPED: new Set(['STARTING', 'RUNNING', 'STOPPED']),
14
+ STARTING: new Set(['RUNNING', 'CRASHED', 'DEGRADED', 'STOPPED']),
15
+ RUNNING: new Set(['DEGRADED', 'CRASHED', 'RESTARTING', 'STOPPED', 'RUNNING']),
16
+ DEGRADED: new Set(['RUNNING', 'CRASHED', 'RESTARTING', 'STOPPED']),
17
+ CRASHED: new Set(['STARTING', 'RESTARTING', 'RUNNING', 'STOPPED']),
18
+ RESTARTING: new Set(['STARTING', 'RUNNING', 'CRASHED', 'STOPPED']),
19
+ }
20
+
21
+ export class ProcessSupervisor {
22
+ /**
23
+ * @param {{
24
+ * name: string,
25
+ * healthcheck?: () => Promise<boolean>,
26
+ * heartbeatMs?: number
27
+ * }} options
28
+ */
29
+ constructor(options = {}) {
30
+ this.name = options.name || 'daemon'
31
+ this.state = DAEMON_STATES.STOPPED
32
+ this.lastError = null
33
+ this.crashCount = 0
34
+ this.startedAt = null
35
+ this.updatedAt = Date.now()
36
+ this.handle = null
37
+ this.disposed = false
38
+ this.healthcheck = typeof options.healthcheck === 'function' ? options.healthcheck : null
39
+ this.heartbeatMs = typeof options.heartbeatMs === 'number' && options.heartbeatMs > 0 ? options.heartbeatMs : 0
40
+ this._timer = null
41
+ this._listeners = new Set()
42
+ this.history = [{ state: this.state, reason: 'init', at: this.updatedAt }]
43
+ }
44
+
45
+ canTransition(nextState) {
46
+ const allowed = VALID_TRANSITIONS[this.state]
47
+ return allowed ? allowed.has(nextState) : false
48
+ }
49
+
50
+ transition(nextState, reason = '') {
51
+ if (!DAEMON_STATES[nextState]) {
52
+ throw new Error(`Invalid daemon state: ${nextState}`)
53
+ }
54
+ const prev = this.state
55
+ this.state = nextState
56
+ this.updatedAt = Date.now()
57
+ if (nextState === DAEMON_STATES.RUNNING) {
58
+ this.lastError = null
59
+ if (!this.startedAt) this.startedAt = this.updatedAt
60
+ } else if (nextState === DAEMON_STATES.CRASHED || nextState === DAEMON_STATES.DEGRADED) {
61
+ if (reason) this.lastError = reason
62
+ if (nextState === DAEMON_STATES.CRASHED) this.crashCount++
63
+ } else if (nextState === DAEMON_STATES.STOPPED) {
64
+ this.startedAt = null
65
+ }
66
+ const entry = { from: prev, state: nextState, reason: reason || '', at: this.updatedAt }
67
+ this.history.push(entry)
68
+ if (this.history.length > 30) this.history.shift()
69
+ for (const fn of this._listeners) {
70
+ try { fn(entry) } catch { /* ignore listener errors */ }
71
+ }
72
+ return this.state
73
+ }
74
+
75
+ onStateChange(listener) {
76
+ if (typeof listener !== 'function') return () => {}
77
+ this._listeners.add(listener)
78
+ return () => this._listeners.delete(listener)
79
+ }
80
+
81
+ attachHandle(handle) {
82
+ this.handle = handle
83
+ if (handle && typeof handle.on === 'function') {
84
+ handle.on('error', (err) => {
85
+ if (!this.disposed) {
86
+ this.transition(DAEMON_STATES.CRASHED, err?.message || String(err))
87
+ }
88
+ })
89
+ handle.on('exit', (code, signal) => {
90
+ if (!this.disposed && code !== 0 && code !== null) {
91
+ this.transition(DAEMON_STATES.CRASHED, `${this.name} process exited (${code ?? signal})`)
92
+ } else if (!this.disposed && this.state === DAEMON_STATES.RUNNING) {
93
+ this.transition(DAEMON_STATES.STOPPED, 'process exited cleanly')
94
+ }
95
+ })
96
+ }
97
+ return handle
98
+ }
99
+
100
+ startHeartbeat() {
101
+ this.stopHeartbeat()
102
+ if (!this.healthcheck || this.heartbeatMs <= 0 || this.disposed) return
103
+ this._timer = setInterval(async () => {
104
+ if (this.disposed || (this.state !== DAEMON_STATES.RUNNING && this.state !== DAEMON_STATES.DEGRADED)) return
105
+ try {
106
+ const ok = await this.healthcheck()
107
+ if (!ok && this.state === DAEMON_STATES.RUNNING) {
108
+ this.transition(DAEMON_STATES.DEGRADED, `${this.name} healthcheck failed`)
109
+ } else if (ok && this.state === DAEMON_STATES.DEGRADED) {
110
+ this.transition(DAEMON_STATES.RUNNING, `${this.name} healthcheck recovered`)
111
+ }
112
+ } catch (err) {
113
+ if (this.state === DAEMON_STATES.RUNNING) {
114
+ this.transition(DAEMON_STATES.DEGRADED, err?.message || String(err))
115
+ }
116
+ }
117
+ }, this.heartbeatMs)
118
+ if (this._timer && typeof this._timer.unref === 'function') {
119
+ this._timer.unref()
120
+ }
121
+ }
122
+
123
+ stopHeartbeat() {
124
+ if (this._timer) {
125
+ clearInterval(this._timer)
126
+ this._timer = null
127
+ }
128
+ }
129
+
130
+ killHandle() {
131
+ if (this.handle && typeof this.handle.kill === 'function') {
132
+ try { this.handle.kill() } catch { /* ignore */ }
133
+ }
134
+ this.handle = null
135
+ }
136
+
137
+ dispose() {
138
+ this.disposed = true
139
+ this.stopHeartbeat()
140
+ this.killHandle()
141
+ this.transition(DAEMON_STATES.STOPPED, 'disposed')
142
+ }
143
+
144
+ snapshot() {
145
+ return {
146
+ name: this.name,
147
+ state: this.state,
148
+ lastError: this.lastError,
149
+ crashCount: this.crashCount,
150
+ startedAt: this.startedAt,
151
+ updatedAt: this.updatedAt,
152
+ }
153
+ }
154
+ }