feat(voice): all existing providers implement HealthyProvider

Adds priority, capabilities, and healthCheck() to:
- DeepgramStreamingSTT (priority 10, realtime)
- ElevenLabsStreamingSTT (priority 20, near-realtime chunked REST)
- ElevenLabsStreamingTTS (priority 10, realtime)
- OpenAIRealtimeTTS (priority 20, premium)
- ElevenLabsBatchTTS (priority 80, batch)
- OpenAIBatchTTS (priority 90, cheap batch)

Each health check hits a lightweight introspection endpoint
(/v1/projects for Deepgram, /v1/user for ElevenLabs, /v1/models for
OpenAI) with a 1s timeout. The healthProbe field is injectable so
tests are deterministic without hitting real networks.

No behaviour change for existing callers — providerId / isStreaming /
startSession() are untouched; only new optional fields added.

Task 7/17.

Author: jddunn

src/voice-pipeline/__tests__/provider-health.spec.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect } from 'vitest';
+import { DeepgramStreamingSTT } from '../providers/DeepgramStreamingSTT.js';
+import { ElevenLabsStreamingSTT } from '../providers/ElevenLabsStreamingSTT.js';
+import { ElevenLabsStreamingTTS } from '../providers/ElevenLabsStreamingTTS.js';
+import { OpenAIRealtimeTTS } from '../providers/OpenAIRealtimeTTS.js';
+import { ElevenLabsBatchTTS } from '../providers/ElevenLabsBatchTTS.js';
+import { OpenAIBatchTTS } from '../providers/OpenAIBatchTTS.js';
+
+describe('provider HealthyProvider implementations', () => {
+  it('Deepgram exposes capabilities + priority', () => {
+    const p = new DeepgramStreamingSTT({ apiKey: 'test' });
+    expect(p.providerId).toBe('deepgram-streaming');
+    expect(p.priority).toBeGreaterThanOrEqual(0);
+    expect(p.capabilities.streaming).toBe(true);
+    expect(p.capabilities.latencyClass).toBe('realtime');
+  });
+
+  it('ElevenLabs STT reports near-realtime latency (chunked REST)', () => {
+    const p = new ElevenLabsStreamingSTT({ apiKey: 'test' });
+    expect(p.providerId).toBe('elevenlabs-streaming-stt');
+    expect(p.capabilities.latencyClass).toBe('near-realtime');
+  });
+
+  it('ElevenLabs streaming TTS capabilities', () => {
+    const p = new ElevenLabsStreamingTTS({ apiKey: 'test' });
+    expect(p.providerId).toBe('elevenlabs-streaming');
+    expect(p.capabilities.streaming).toBe(true);
+  });
+
+  it('OpenAI Realtime TTS capabilities', () => {
+    const p = new OpenAIRealtimeTTS({ apiKey: 'test' });
+    expect(p.providerId).toBe('openai-realtime');
+    expect(p.capabilities.streaming).toBe(true);
+  });
+
+  it('ElevenLabs Batch TTS is non-streaming', () => {
+    const p = new ElevenLabsBatchTTS({ apiKey: 'test' });
+    expect(p.providerId).toBe('elevenlabs-batch');
+    expect(p.capabilities.streaming).toBe(false);
+    expect(p.capabilities.latencyClass).toBe('batch');
+  });
+
+  it('OpenAI Batch TTS is non-streaming', () => {
+    const p = new OpenAIBatchTTS({ apiKey: 'test' });
+    expect(p.providerId).toMatch(/^openai-/);
+    expect(p.capabilities.streaming).toBe(false);
+    expect(p.capabilities.latencyClass).toBe('batch');
+  });
+
+  it('healthCheck returns auth failure on 401 from probe', async () => {
+    const p = new ElevenLabsStreamingTTS({
+      apiKey: 'bogus',
+      healthProbe: async () => ({ ok: false, status: 401, latencyMs: 50 }),
+    });
+    const result = await p.healthCheck();
+    expect(result.ok).toBe(false);
+    expect(result.error?.class).toBe('auth');
+  });
+
+  it('healthCheck returns ok when probe succeeds', async () => {
+    const p = new ElevenLabsStreamingTTS({
+      apiKey: 'valid',
+      healthProbe: async () => ({ ok: true, status: 200, latencyMs: 30 }),
+    });
+    const result = await p.healthCheck();
+    expect(result.ok).toBe(true);
+    expect(result.latencyMs).toBe(30);
+  });
+
+  it('healthCheck catches thrown errors (network)', async () => {
+    const p = new DeepgramStreamingSTT({
+      apiKey: 'valid',
+      healthProbe: async () => {
+        throw Object.assign(new Error('ECONNRESET'), { code: 'ECONNRESET' });
+      },
+    });
+    const result = await p.healthCheck();
+    expect(result.ok).toBe(false);
+    expect(result.error?.class).toBe('network');
+  });
+});

src/voice-pipeline/providers/DeepgramStreamingSTT.ts

@@ -35,6 +35,34 @@ import type {
   TranscriptEvent,
   TranscriptWord,
 } from '../types.js';
+import {
+  defaultCapabilities,
+  type HealthyProvider,
+  type HealthCheckResult,
+  type ProviderCapabilities,
+} from '../HealthyProvider.js';
+import { VoicePipelineError } from '../VoicePipelineError.js';
+
+/**
+ * Shape of the injected health probe used for deterministic tests.
+ * Default implementation hits Deepgram's /v1/projects endpoint.
+ */
+export type VoiceHealthProbe = (
+  apiKey: string
+) => Promise<{ ok: boolean; status: number; latencyMs: number }>;
+
+async function defaultDeepgramProbe(apiKey: string) {
+  const start = Date.now();
+  try {
+    const res = await fetch('https://api.deepgram.com/v1/projects', {
+      headers: { Authorization: `Token ${apiKey}` },
+      signal: AbortSignal.timeout(1000),
+    });
+    return { ok: res.ok, status: res.status, latencyMs: Date.now() - start };
+  } catch (err) {
+    throw err;
+  }
+}
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -58,6 +86,18 @@ export interface DeepgramStreamingSTTConfig {
    * @default 'nova-2'
    */
   model?: string;
+
+  /**
+   * Chain priority. Lower values are tried first.
+   * @default 10
+   */
+  priority?: number;
+
+  /** Optional capability overrides. Merged into defaultCapabilities(). */
+  capabilities?: Partial<ProviderCapabilities>;
+
+  /** Injectable health probe for tests. Defaults to Deepgram /v1/projects. */
+  healthProbe?: VoiceHealthProbe;
 }
 
 // ---------------------------------------------------------------------------
@@ -331,13 +371,54 @@ class DeepgramStreamingSTTSession extends EventEmitter implements StreamingSTTSe
  * session.on('transcript', (event) => console.log(event.text));
  * ```
  */
-export class DeepgramStreamingSTT implements IStreamingSTT {
+export class DeepgramStreamingSTT implements IStreamingSTT, HealthyProvider {
   readonly providerId = 'deepgram-streaming';
   readonly isStreaming = true;
+  readonly priority: number;
+  readonly capabilities: ProviderCapabilities;
   private readonly keyPool: ApiKeyPool;
+  private readonly healthProbe: VoiceHealthProbe;
 
   constructor(private readonly config: DeepgramStreamingSTTConfig) {
     this.keyPool = new ApiKeyPool(config.apiKey);
+    this.priority = config.priority ?? 10;
+    this.capabilities = defaultCapabilities({
+      languages: ['*'],
+      streaming: true,
+      costTier: 'standard',
+      latencyClass: 'realtime',
+      ...(config.capabilities ?? {}),
+    });
+    this.healthProbe = config.healthProbe ?? defaultDeepgramProbe;
+  }
+
+  async healthCheck(): Promise<HealthCheckResult> {
+    if (!this.keyPool.hasKeys) {
+      return { ok: false, error: { class: 'auth', message: 'no api key available' } };
+    }
+    const key = this.keyPool.next();
+    try {
+      const res = await this.healthProbe(key);
+      if (res.ok) return { ok: true, latencyMs: res.latencyMs };
+      const classified = VoicePipelineError.classifyError(
+        new Error(`HTTP ${res.status}`),
+        { kind: 'stt', provider: this.providerId }
+      );
+      return {
+        ok: false,
+        latencyMs: res.latencyMs,
+        error: { class: classified.errorClass, message: `HTTP ${res.status}` },
+      };
+    } catch (err) {
+      const classified = VoicePipelineError.classifyError(err, {
+        kind: 'stt',
+        provider: this.providerId,
+      });
+      return {
+        ok: false,
+        error: { class: classified.errorClass, message: classified.message },
+      };
+    }
   }
 
   /**

src/voice-pipeline/providers/ElevenLabsBatchTTS.ts

@@ -8,6 +8,22 @@
 import type { IBatchTTS, BatchTTSConfig, BatchTTSResult } from '../types.js';
 import { ApiKeyPool } from '../../core/providers/ApiKeyPool.js';
 import { isQuotaError } from '../../core/providers/quotaErrors.js';
+import {
+  defaultCapabilities,
+  type HealthyProvider,
+  type HealthCheckResult,
+  type ProviderCapabilities,
+} from '../HealthyProvider.js';
+import { VoicePipelineError } from '../VoicePipelineError.js';
+
+async function defaultElevenLabsBatchProbe(apiKey: string) {
+  const start = Date.now();
+  const res = await fetch('https://api.elevenlabs.io/v1/user', {
+    headers: { 'xi-api-key': apiKey },
+    signal: AbortSignal.timeout(1000),
+  });
+  return { ok: res.ok, status: res.status, latencyMs: Date.now() - start };
+}
 
 /** Configuration for the ElevenLabs batch TTS provider. */
 export interface ElevenLabsBatchTTSConfig {
@@ -19,6 +35,12 @@ export interface ElevenLabsBatchTTSConfig {
   model?: string;
   /** Base URL for the ElevenLabs API. Defaults to 'https://api.elevenlabs.io/v1'. */
   baseUrl?: string;
+  /** Chain priority. Lower values are tried first. @default 80 */
+  priority?: number;
+  /** Optional capability overrides. */
+  capabilities?: Partial<ProviderCapabilities>;
+  /** Injectable health probe for tests. */
+  healthProbe?: (apiKey: string) => Promise<{ ok: boolean; status: number; latencyMs: number }>;
 }
 
 /** Approximate bytes per second for 128kbps MP3 audio. */
@@ -30,8 +52,10 @@ const BYTES_PER_SEC_MP3 = 16_000;
  * Accepts complete text and returns finished MP3 audio with voice settings
  * control via `providerOptions` (stability, similarityBoost, style, useSpeakerBoost).
  */
-export class ElevenLabsBatchTTS implements IBatchTTS {
+export class ElevenLabsBatchTTS implements IBatchTTS, HealthyProvider {
   readonly providerId = 'elevenlabs-batch';
+  readonly priority: number;
+  readonly capabilities: ProviderCapabilities;
 
   /** API key pool for round-robin rotation and quota failover. */
   private readonly keyPool: ApiKeyPool;
@@ -45,11 +69,52 @@ export class ElevenLabsBatchTTS implements IBatchTTS {
   /** Base URL for all API requests. */
   private readonly baseUrl: string;
 
+  /** Injectable health probe for tests. */
+  private readonly healthProbe: NonNullable<ElevenLabsBatchTTSConfig['healthProbe']>;
+
   constructor(config: ElevenLabsBatchTTSConfig) {
     this.keyPool = new ApiKeyPool(config.apiKey);
     this.defaultVoiceId = config.voiceId ?? 'EXAVITQu4vr4xnSDxMaL';
     this.model = config.model ?? 'eleven_multilingual_v2';
     this.baseUrl = config.baseUrl ?? 'https://api.elevenlabs.io/v1';
+    this.priority = config.priority ?? 80;
+    this.capabilities = defaultCapabilities({
+      languages: ['*'],
+      streaming: false,
+      costTier: 'standard',
+      latencyClass: 'batch',
+      ...(config.capabilities ?? {}),
+    });
+    this.healthProbe = config.healthProbe ?? defaultElevenLabsBatchProbe;
+  }
+
+  async healthCheck(): Promise<HealthCheckResult> {
+    if (!this.keyPool.hasKeys) {
+      return { ok: false, error: { class: 'auth', message: 'no api key available' } };
+    }
+    const key = this.keyPool.next();
+    try {
+      const res = await this.healthProbe(key);
+      if (res.ok) return { ok: true, latencyMs: res.latencyMs };
+      const classified = VoicePipelineError.classifyError(
+        new Error(`HTTP ${res.status}`),
+        { kind: 'tts', provider: this.providerId }
+      );
+      return {
+        ok: false,
+        latencyMs: res.latencyMs,
+        error: { class: classified.errorClass, message: `HTTP ${res.status}` },
+      };
+    } catch (err) {
+      const classified = VoicePipelineError.classifyError(err, {
+        kind: 'tts',
+        provider: this.providerId,
+      });
+      return {
+        ok: false,
+        error: { class: classified.errorClass, message: classified.message },
+      };
+    }
   }
 
   /**

src/voice-pipeline/providers/ElevenLabsStreamingSTT.ts

@@ -34,6 +34,22 @@ import type {
   TranscriptWord,
 } from '../types.js';
 import { ApiKeyPool } from '../../core/providers/ApiKeyPool.js';
+import {
+  defaultCapabilities,
+  type HealthyProvider,
+  type HealthCheckResult,
+  type ProviderCapabilities,
+} from '../HealthyProvider.js';
+import { VoicePipelineError } from '../VoicePipelineError.js';
+
+async function defaultElevenLabsProbe(apiKey: string) {
+  const start = Date.now();
+  const res = await fetch('https://api.elevenlabs.io/v1/user', {
+    headers: { 'xi-api-key': apiKey },
+    signal: AbortSignal.timeout(1000),
+  });
+  return { ok: res.ok, status: res.status, latencyMs: Date.now() - start };
+}
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -57,6 +73,15 @@ export interface ElevenLabsStreamingSTTConfig {
    * @default 'scribe_v1'
    */
   model?: string;
+
+  /** Chain priority. Lower values are tried first. @default 20 */
+  priority?: number;
+
+  /** Optional capability overrides. */
+  capabilities?: Partial<ProviderCapabilities>;
+
+  /** Injectable health probe for tests. */
+  healthProbe?: (apiKey: string) => Promise<{ ok: boolean; status: number; latencyMs: number }>;
 }
 
 // ---------------------------------------------------------------------------
@@ -333,13 +358,56 @@ class ElevenLabsChunkedSTTSession extends EventEmitter implements StreamingSTTSe
  * session.on('transcript', (event) => console.log(event.text));
  * ```
  */
-export class ElevenLabsStreamingSTT implements IStreamingSTT {
+export class ElevenLabsStreamingSTT implements IStreamingSTT, HealthyProvider {
   readonly providerId = 'elevenlabs-streaming-stt';
   readonly isStreaming = true;
+  readonly priority: number;
+  readonly capabilities: ProviderCapabilities;
   private readonly keyPool: ApiKeyPool;
+  private readonly healthProbe: NonNullable<
+    ElevenLabsStreamingSTTConfig['healthProbe']
+  >;
 
   constructor(private readonly config: ElevenLabsStreamingSTTConfig) {
     this.keyPool = new ApiKeyPool(config.apiKey);
+    this.priority = config.priority ?? 20;
+    this.capabilities = defaultCapabilities({
+      languages: ['*'],
+      streaming: true,
+      costTier: 'standard',
+      latencyClass: 'near-realtime',
+      ...(config.capabilities ?? {}),
+    });
+    this.healthProbe = config.healthProbe ?? defaultElevenLabsProbe;
+  }
+
+  async healthCheck(): Promise<HealthCheckResult> {
+    if (!this.keyPool.hasKeys) {
+      return { ok: false, error: { class: 'auth', message: 'no api key available' } };
+    }
+    const key = this.keyPool.next();
+    try {
+      const res = await this.healthProbe(key);
+      if (res.ok) return { ok: true, latencyMs: res.latencyMs };
+      const classified = VoicePipelineError.classifyError(
+        new Error(`HTTP ${res.status}`),
+        { kind: 'stt', provider: this.providerId }
+      );
+      return {
+        ok: false,
+        latencyMs: res.latencyMs,
+        error: { class: classified.errorClass, message: `HTTP ${res.status}` },
+      };
+    } catch (err) {
+      const classified = VoicePipelineError.classifyError(err, {
+        kind: 'stt',
+        provider: this.providerId,
+      });
+      return {
+        ok: false,
+        error: { class: classified.errorClass, message: classified.message },
+      };
+    }
   }
 
   /**