@goodandready/dsh-voice 0.9.46 → 0.9.47

package/lib/chain.js

@@ -1,21 +1,18 @@
 // Provider fallback chain. No network and no cordis — a pure function so
 // failure behaviour is unit-testable.
-
-function normalizeError(err) {
-  const cause = err?.cause?.message || err?.message || String(err)
-  return cause.slice(0, 200)
-}
+import { classifyProviderOutcome, shouldFallbackError, ChainExhaustedError } from './errors.js'
 
 /**
  * @param order {string[]} provider keys in attempt order
- * @param providers {Record<string, () => Promise<{ok, provider?, text?, reason?}>>}
- * @param onAttempt {(provider: string, res: {ok: boolean, tookMs: number, reason?: string}) => void} optional stats callback
+ * @param providers {Record<string, () => Promise<{ok, provider?, text?, reason?, code?, fallbackEligible?}>>}
+ * @param onAttempt {(provider: string, res: {ok: boolean, tookMs: number, reason?: string, code?: string}) => void} optional stats callback
  * @returns {Promise<{provider: string, text: string, tookMs: number}>}
  */
 export async function runChain(order, providers, onAttempt) {
   const t0 = Date.now()
   const keys = (Array.isArray(order) ? order : []).filter((k) => typeof providers[k] === 'function')
   const errors = []
+  const attempts = []
   for (const key of keys) {
     const startT = Date.now()
     try {
@@ -27,19 +24,55 @@ export async function runChain(order, providers, onAttempt) {
         }
         return { provider: out.provider || key, text: out.text, tookMs: Date.now() - t0 }
       }
-      const reason = (out && out.reason) || 'unknown'
+      const classified = classifyProviderOutcome((out && out.provider) || key, out || { reason: 'unknown' })
+      const pName = classified.provider || key
       if (typeof onAttempt === 'function') {
-        onAttempt((out && out.provider) || key, { ok: false, tookMs, reason })
+        onAttempt(pName, { ok: false, tookMs, reason: classified.message, code: classified.code })
+      }
+      attempts.push({
+        provider: pName,
+        code: classified.code,
+        reason: classified.message,
+        tookMs,
+        isRetryable: classified.isRetryable,
+      })
+      errors.push(`${pName}: ${classified.message}`)
+      if (!shouldFallbackError(classified)) {
+        throw classified
       }
-      errors.push(`${(out && out.provider) || key}: ${reason}`)
     } catch (err) {
       const tookMs = Date.now() - startT
-      const normErr = normalizeError(err)
+      const classified = classifyProviderOutcome(key, err)
+      if (!shouldFallbackError(classified)) {
+        const alreadyRecorded = attempts.some(
+          (a) => a.provider === (classified.provider || key) && a.reason === classified.message
+        )
+        if (!alreadyRecorded && typeof onAttempt === 'function') {
+          onAttempt(classified.provider || key, {
+            ok: false,
+            tookMs,
+            reason: classified.message,
+            code: classified.code,
+          })
+        }
+        throw classified
+      }
       if (typeof onAttempt === 'function') {
-        onAttempt(key, { ok: false, tookMs, reason: normErr })
+        onAttempt(key, { ok: false, tookMs, reason: classified.message, code: classified.code })
       }
-      errors.push(`${key}: ${normErr}`)
+      attempts.push({
+        provider: key,
+        code: classified.code,
+        reason: classified.message,
+        tookMs,
+        isRetryable: classified.isRetryable,
+      })
+      errors.push(`${key}: ${classified.message}`)
     }
   }
-  throw new Error(`all providers failed (${errors.join('; ')})`)
+  const anyRetryable = attempts.some((a) => a.isRetryable)
+  throw new ChainExhaustedError(`all providers failed (${errors.join('; ')})`, {
+    attempts,
+    isRetryable: anyRetryable,
+  })
 }

package/lib/config-compat.js

@@ -1,3 +1,5 @@
+export { isVolatileRef, plainConfig, resolveConfig, markVolatile, makeVolatile } from './schema.js'
+
 // Decode modern volatile Config references while retaining stable identities for
 // the request hot path. Legacy cores pass ordinary resolved configuration.
 // If ctx is provided, invalidation listeners cache the unwrapped tree so the hot

package/lib/errors.js

@@ -0,0 +1,252 @@
+// lib/errors.js — Typed domain error hierarchy and failure classification (#309)
+
+export class VoiceError extends Error {
+  /**
+   * @param {string} message
+   * @param {{
+   *   code?: string,
+   *   provider?: string,
+   *   status?: number,
+   *   isRetryable?: boolean,
+   *   fallbackEligible?: boolean,
+   *   retryAfterMs?: number,
+   *   cause?: unknown
+   * }} [options]
+   */
+  constructor(message, options = {}) {
+    super(message)
+    this.name = new.target.name
+    this.code = options.code || 'VOICE_ERROR'
+    this.provider = options.provider || ''
+    if (typeof options.status === 'number') this.status = options.status
+    this.isRetryable = Boolean(options.isRetryable)
+    this.fallbackEligible = options.fallbackEligible !== false
+    if (typeof options.retryAfterMs === 'number') this.retryAfterMs = options.retryAfterMs
+    if (options.cause !== undefined) this.cause = options.cause
+  }
+
+  /**
+   * Whether the STT fallback chain should advance to the next provider.
+   * @returns {boolean}
+   */
+  shouldFallback() {
+    return this.fallbackEligible
+  }
+
+  toJSON() {
+    return {
+      ok: false,
+      code: this.code,
+      message: this.message,
+      ...(this.provider ? { provider: this.provider } : {}),
+      ...(this.status !== undefined ? { status: this.status } : {}),
+      isRetryable: this.isRetryable,
+      fallbackEligible: this.fallbackEligible,
+      ...(this.retryAfterMs !== undefined ? { retryAfterMs: this.retryAfterMs } : {}),
+    }
+  }
+}
+
+export class ProviderAuthError extends VoiceError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || 'PROVIDER_AUTH_ERROR',
+      isRetryable: false,
+      fallbackEligible: options.fallbackEligible !== false,
+    })
+  }
+}
+
+export class ProviderQuotaError extends VoiceError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || 'PROVIDER_QUOTA_ERROR',
+      isRetryable: false,
+      fallbackEligible: options.fallbackEligible !== false,
+    })
+  }
+}
+
+export class ProviderRateLimitError extends VoiceError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || 'PROVIDER_RATE_LIMIT',
+      isRetryable: true,
+      fallbackEligible: options.fallbackEligible !== false,
+    })
+  }
+}
+
+export class ProviderServerError extends VoiceError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || 'PROVIDER_SERVER_ERROR',
+      isRetryable: options.isRetryable ?? true,
+      fallbackEligible: options.fallbackEligible !== false,
+    })
+  }
+}
+
+export class DaemonUnavailableError extends VoiceError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || 'DAEMON_UNAVAILABLE',
+      isRetryable: false,
+      fallbackEligible: options.fallbackEligible !== false,
+    })
+  }
+}
+
+export class AudioFormatError extends VoiceError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || 'AUDIO_FORMAT_ERROR',
+      isRetryable: false,
+      fallbackEligible: Boolean(options.fallbackEligible),
+    })
+  }
+}
+
+export class ChainExhaustedError extends VoiceError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      code: options.code || 'CHAIN_EXHAUSTED',
+      isRetryable: Boolean(options.isRetryable),
+      fallbackEligible: false,
+    })
+    this.attempts = Array.isArray(options.attempts) ? options.attempts : []
+  }
+
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      attempts: this.attempts,
+    }
+  }
+}
+
+export function isQuotaText(detail = '') {
+  const lower = String(detail).toLowerCase()
+  return /\bquota\b/.test(lower)
+    || lower.includes('usage limit')
+    || lower.includes('usage_limit')
+    || lower.includes('limit reached')
+    || lower.includes('insufficient credit')
+    || lower.includes('insufficient balance')
+    || lower.includes('insufficient funds')
+    || lower.includes('credit balance')
+    || lower.includes('out of credit')
+    || lower.includes('payment required')
+    || lower.includes('billing')
+}
+
+export function parseRetryAfterMs(headers) {
+  if (!headers || typeof headers.get !== 'function') return undefined
+  const raw = headers.get('retry-after')
+  if (raw === null || raw === undefined || String(raw).trim() === '') return undefined
+  const seconds = Number(raw)
+  if (Number.isFinite(seconds) && seconds >= 0) return Math.trunc(seconds * 1000)
+  const at = Date.parse(raw)
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : undefined
+}
+
+/**
+ * Classify an HTTP status and message into a typed VoiceError subclass.
+ * @param {string} provider
+ * @param {number} status
+ * @param {string} message
+ * @param {Headers} [headers]
+ * @returns {VoiceError}
+ */
+export function classifyHttpError(provider, status, message, headers) {
+  const msg = String(message || `HTTP ${status}`).trim()
+  const retryAfterMs = parseRetryAfterMs(headers)
+  const opts = { provider, status, ...(retryAfterMs !== undefined ? { retryAfterMs } : {}) }
+
+  if (status === 402 || (isQuotaText(msg) && status !== 401)) {
+    return new ProviderQuotaError(msg, opts)
+  }
+  if (status === 401 || status === 403) {
+    return new ProviderAuthError(msg, opts)
+  }
+  if (status === 429) {
+    return new ProviderRateLimitError(msg, opts)
+  }
+  if (status === 415 || status === 422) {
+    return new AudioFormatError(msg, { ...opts, fallbackEligible: true })
+  }
+  if (status === 408 || status === 504 || status >= 500) {
+    return new ProviderServerError(msg, opts)
+  }
+  return new VoiceError(msg, { ...opts, code: 'PROVIDER_HTTP_ERROR', isRetryable: false, fallbackEligible: true })
+}
+
+/**
+ * Classify a provider refusal object or thrown Error into a VoiceError.
+ * @param {string} provider
+ * @param {unknown} outcomeOrErr
+ * @returns {VoiceError}
+ */
+export function classifyProviderOutcome(provider, outcomeOrErr) {
+  if (outcomeOrErr instanceof VoiceError) {
+    if (!outcomeOrErr.provider && provider) outcomeOrErr.provider = provider
+    return outcomeOrErr
+  }
+  if (outcomeOrErr instanceof Error) {
+    const rawMsg = outcomeOrErr?.cause?.message || outcomeOrErr?.message || String(outcomeOrErr)
+    const msg = rawMsg.slice(0, 200)
+    const statusMatch = msg.match(/\bHTTP\s+(\d{3})\b/i)
+    if (statusMatch) {
+      return classifyHttpError(provider, Number(statusMatch[1]), msg)
+    }
+    if (isQuotaText(msg)) {
+      return new ProviderQuotaError(msg, { provider, cause: outcomeOrErr })
+    }
+    if (/econnrefused|enotfound|fetch failed|daemon|not running|offline/i.test(msg)) {
+      return new DaemonUnavailableError(msg, { provider, cause: outcomeOrErr })
+    }
+    return new VoiceError(msg, {
+      provider,
+      code: 'PROVIDER_RUNTIME_ERROR',
+      isRetryable: /timeout|timed out|aborted|network/i.test(msg),
+      fallbackEligible: true,
+      cause: outcomeOrErr,
+    })
+  }
+  if (outcomeOrErr && typeof outcomeOrErr === 'object') {
+    const reason = String(outcomeOrErr.reason || outcomeOrErr.message || 'unknown').slice(0, 200)
+    const p = String(outcomeOrErr.provider || provider || '')
+    const fallbackEligible = outcomeOrErr.fallbackEligible !== false
+    if (outcomeOrErr.code === 'AUDIO_FORMAT_ERROR') {
+      return new AudioFormatError(reason, { provider: p, fallbackEligible })
+    }
+    if (/^no\s+[A-Z0-9_]+/i.test(reason) || /unauthorized|invalid.*key|forbidden/i.test(reason)) {
+      return new ProviderAuthError(reason, { provider: p, fallbackEligible })
+    }
+    if (isQuotaText(reason)) {
+      return new ProviderQuotaError(reason, { provider: p, fallbackEligible })
+    }
+    if (/offline|unreachable|not running|recognition runs in the page/i.test(reason)) {
+      return new DaemonUnavailableError(reason, { provider: p, fallbackEligible })
+    }
+    return new VoiceError(reason, {
+      provider: p,
+      code: outcomeOrErr.code || 'PROVIDER_REFUSAL',
+      isRetryable: false,
+      fallbackEligible,
+    })
+  }
+  return new VoiceError(String(outcomeOrErr || 'unknown').slice(0, 200), { provider })
+}
+
+export function shouldFallbackError(err) {
+  if (err instanceof VoiceError) return err.shouldFallback()
+  return true
+}

package/lib/host-routes.js

@@ -357,7 +357,16 @@ export function registerHostRoutes(ctx, deps) {
             lowVolume: Boolean(payload.lowVolume),
           })
         }
-        writeJson(res, 502, { ok: false, error: { code: 'chain', message: String(e && e.message || e) } })
+        writeJson(res, 502, {
+          ok: false,
+          error: {
+            code: 'chain',
+            domainCode: (e && e.code) || 'CHAIN_EXHAUSTED',
+            isRetryable: Boolean(e && e.isRetryable),
+            ...(Array.isArray(e && e.attempts) ? { attempts: e.attempts } : {}),
+            message: String(e && e.message || e),
+          },
+        })
       } finally {
         clearTimeout(timer)
       }

package/lib/index.js

@@ -23,48 +23,57 @@ import { createPolishText } from './polish.js'
 import { buildProviderOrder, sessionCommand } from './transcribe-core.js'
 import { createUserMessage } from '@deepseek-ai/dsh-llm'
 import { applyJargonDictionary, extractVoiceActions } from './normalize.js'
-import { ChainEntry, CustomProvider, BaseConfig } from './schema.js'
+import {
+  ChainEntry,
+  CustomProvider,
+  BaseConfig,
+  markVolatile,
+  makeVolatile as schemaMakeVolatile,
+  isVolatileRef,
+  plainConfig,
+  resolveConfig,
+} from './schema.js'
+import {
+  VoiceError,
+  ProviderAuthError,
+  ProviderQuotaError,
+  ProviderRateLimitError,
+  ProviderServerError,
+  DaemonUnavailableError,
+  AudioFormatError,
+  ChainExhaustedError,
+} from './errors.js'
 import { createLocalDaemons } from './local-daemon.js'
 
-export { ChainEntry, CustomProvider, BaseConfig }
+export {
+  ChainEntry,
+  CustomProvider,
+  BaseConfig,
+  markVolatile,
+  isVolatileRef,
+  plainConfig,
+  resolveConfig,
+  VoiceError,
+  ProviderAuthError,
+  ProviderQuotaError,
+  ProviderRateLimitError,
+  ProviderServerError,
+  DaemonUnavailableError,
+  AudioFormatError,
+  ChainExhaustedError,
+}
 export const name = '@goodandready/dsh-voice'
 export const NS = 'dsh-voice'
 export const inject = ['tools', 'credentials', 'webServer', 'shell', 'settings', 'llm']
 
 function makeVolatile(schema) {
-  if (!schema || typeof schema !== 'object' || !schema.dict) return schema
-  const dict = {}
-  for (const [k, v] of Object.entries(schema.dict)) {
-    dict[k] = (v && typeof v.volatile === 'function') ? v.volatile() : v
-  }
-  const res = z.object(dict)
-  if (typeof schema.description === 'function' && schema.meta?.description) {
-    return res.description(schema.meta.description)
-  }
-  return res
+  return schemaMakeVolatile(schema)
 }
 
 export const Config = typeof z.number().volatile === 'function'
   ? makeVolatile(BaseConfig)
   : BaseConfig
 
-export function isVolatileRef(value) {
-  return value !== null && typeof value === 'object' && !Array.isArray(value) && typeof value.get === 'function'
-}
-
-export function plainConfig(value) {
-  while (typeof value === 'function') {
-    value = value()
-  }
-  if (isVolatileRef(value)) return plainConfig(value.get())
-  if (value === null || typeof value !== 'object') return value
-  if (value instanceof Date || value instanceof RegExp || (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))) {
-    return value
-  }
-  if (Array.isArray(value)) return value.map(plainConfig)
-  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, plainConfig(v)]))
-}
-
 export function apply(ctx, baseConfig) {
   let settingsService = null
   let scope = null
@@ -84,12 +93,9 @@ export function apply(ctx, baseConfig) {
 
   const live = () => {
     try {
-      const raw = getConfig() ?? {}
-      const unwrapped = plainConfig(raw)
-      const validated = BaseConfig(unwrapped)
-      return plainConfig(validated) ?? plainConfig(readEntryConfig())
+      return resolveConfig(getConfig() ?? readEntryConfig())
     } catch {
-      return plainConfig(readEntryConfig())
+      return resolveConfig(readEntryConfig())
     }
   }
 

package/lib/provider-http.js

@@ -1,4 +1,5 @@
 // Pure helper functions for STT provider HTTP requests and responses.
+import { classifyHttpError } from './errors.js'
 
 /**
  * Check if the language is unspecified or set to automatic detection.
@@ -62,3 +63,15 @@ export async function readErrorDetail(res, defaultLabel) {
   } catch { /* not json */ }
   return `${defaultLabel} ${detail}`
 }
+
+/**
+ * Extract and classify a non-2xx HTTP response into a typed VoiceError subclass.
+ * @param {Response} res
+ * @param {string} defaultLabel
+ * @param {string} [providerKey]
+ * @returns {Promise<import('./errors.js').VoiceError>}
+ */
+export async function readHttpError(res, defaultLabel, providerKey = '') {
+  const detail = await readErrorDetail(res, defaultLabel)
+  return classifyHttpError(providerKey || defaultLabel.toLowerCase(), res?.status || 500, detail, res?.headers)
+}

package/lib/providers.js

@@ -68,8 +68,8 @@ const CHAT_AUDIO_PROMPT =
   'Transcribe the audio verbatim. Reply with the transcript text only, '
   + 'without comments, quotes or formatting.'
 
-import { readErrorDetail, safeJson, isAutoLang, fileName, chatAudioFormat } from './provider-http.js'
-export { readErrorDetail, safeJson, isAutoLang, fileName, chatAudioFormat }
+import { readErrorDetail, readHttpError, safeJson, isAutoLang, fileName, chatAudioFormat } from './provider-http.js'
+export { readErrorDetail, readHttpError, safeJson, isAutoLang, fileName, chatAudioFormat }
 
 export const DEFAULT_MODELS = {
   deepgram: 'nova-2',
@@ -110,7 +110,7 @@ export function makeProviders(deps, req) {
       signal,
       keepalive: true,
     })
-    if (!res.ok) throw new Error(await readErrorDetail(res, 'Deepgram'))
+    if (!res.ok) throw await readHttpError(res, 'Deepgram', 'deepgram')
     let data
     try { data = await safeJson(res, 'Deepgram') } catch (e) {
       return { ok: false, provider: 'deepgram', reason: e.message }
@@ -135,7 +135,7 @@ export function makeProviders(deps, req) {
       signal,
       keepalive: true,
     })
-    if (!res.ok) throw new Error(await readErrorDetail(res, 'Groq'))
+    if (!res.ok) throw await readHttpError(res, 'Groq', 'groq')
     let data
     try { data = await safeJson(res, 'Groq') } catch (e) {
       return { ok: false, provider: 'groq', reason: e.message }
@@ -155,7 +155,7 @@ export function makeProviders(deps, req) {
       signal,
       keepalive: true,
     })
-    if (!res.ok) throw new Error(await readErrorDetail(res, 'HF'))
+    if (!res.ok) throw await readHttpError(res, 'HF', 'hf')
     let data
     try { data = await safeJson(res, 'HF') } catch (e) {
       return { ok: false, provider: 'hf', reason: e.message }
@@ -289,7 +289,7 @@ export function makeProviders(deps, req) {
       const res = await fetchImpl(`${base}/audio/transcriptions`, {
         method: 'POST', headers, body: form, signal,
       })
-      if (!res.ok) throw new Error(await readErrorDetail(res, label))
+      if (!res.ok) throw await readHttpError(res, label, spec.key)
       const data = await safeJson(res, label)
       return (data?.text || '').trim()
     }
@@ -322,7 +322,7 @@ export function makeProviders(deps, req) {
         }),
         signal,
       })
-      if (!res.ok) throw new Error(await readErrorDetail(res, label))
+      if (!res.ok) throw await readHttpError(res, label, spec.key)
       const data = await safeJson(res, label)
       return String(data?.choices?.[0]?.message?.content || '').trim()
     }

package/lib/schema.js

@@ -181,3 +181,68 @@ export const BaseConfig = z.object({
   voiceMacros: z.array(VoiceMacro).default([])
     .description('User voice action macros (spoken trigger phrase -> structured prompt replacement).'),
 })
+
+export function markVolatile(schema) {
+  return (schema && typeof schema.volatile === 'function') ? schema.volatile() : schema
+}
+
+export function makeVolatile(schema) {
+  if (!schema || typeof schema !== 'object' || !schema.dict) return markVolatile(schema)
+  const dict = {}
+  for (const [k, v] of Object.entries(schema.dict)) {
+    dict[k] = markVolatile(v)
+  }
+  const res = z.object(dict)
+  if (typeof schema.description === 'function' && schema.meta?.description) {
+    return res.description(schema.meta.description)
+  }
+  return res
+}
+
+export const Config = typeof z.number().volatile === 'function'
+  ? makeVolatile(BaseConfig)
+  : BaseConfig
+
+export function isVolatileRef(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) && typeof value.get === 'function'
+}
+
+export function plainConfig(value) {
+  while (typeof value === 'function') {
+    value = value()
+  }
+  if (isVolatileRef(value)) return plainConfig(value.get())
+  if (value === null || typeof value !== 'object') return value
+  if (value instanceof Date || value instanceof RegExp || (typeof Buffer !== 'undefined' && Buffer.isBuffer(value))) {
+    return value
+  }
+  if (Array.isArray(value)) return value.map(plainConfig)
+  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, plainConfig(v)]))
+}
+
+/**
+ * Normalize raw configuration (including volatile boxes or partial settings)
+ * into a deterministic validated configuration object (#305).
+ */
+export function resolveConfig(rawConfig) {
+  const unwrapped = plainConfig(rawConfig ?? {})
+  const input = (unwrapped && typeof unwrapped === 'object' && !Array.isArray(unwrapped)) ? unwrapped : {}
+  let validated
+  try {
+    validated = plainConfig(BaseConfig(structuredClone(input)))
+  } catch {
+    const defaults = plainConfig(BaseConfig({}))
+    validated = { ...defaults, ...input }
+    if (typeof validated.lowVolumeThreshold !== 'number' || !Number.isFinite(validated.lowVolumeThreshold)) {
+      validated.lowVolumeThreshold = defaults.lowVolumeThreshold
+    } else {
+      validated.lowVolumeThreshold = Math.min(1, Math.max(0, validated.lowVolumeThreshold))
+    }
+  }
+  return {
+    ...validated,
+    deepgramBaseUrl: String(validated.deepgramBaseUrl || 'https://api.deepgram.com').trim() || 'https://api.deepgram.com',
+    whisperUrl: String(validated.whisperUrl || 'http://127.0.0.1:8001/inference').trim() || 'http://127.0.0.1:8001/inference',
+    sensevoiceUrl: String(validated.sensevoiceUrl || 'http://127.0.0.1:6006/api/v1/asr').trim() || 'http://127.0.0.1:6006/api/v1/asr',
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-voice",
-  "version": "0.9.46",
+  "version": "0.9.47",
   "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, plus any OpenAI-compatible API of your own).",
   "license": "MIT",
   "type": "module",