feat(voice): VoicePipelineError + AggregateVoiceError with structured classification

Adds a Error subclass carrying { kind, provider, errorClass, retryable,
cause } so chains and circuit breakers can react to failures without
parsing error.message. classifyError() maps common HTTP + Node error
shapes (401/403/auth, 429/rate-limit, 5xx/service, ECONNRESET/network)
into the HealthErrorClass union.

Foundation for the voice pipeline resilience plan (Task 1/17).

Author: jddunn

src/voice-pipeline/VoicePipelineError.ts

@@ -0,0 +1,105 @@
+/**
+ * @module voice-pipeline/VoicePipelineError
+ *
+ * Structured error class for voice pipeline failures. Carries enough shape
+ * for chains and circuit breakers to classify and react without stringly
+ * matching error.message.
+ */
+
+export type HealthErrorClass =
+  | 'auth'
+  | 'quota'
+  | 'network'
+  | 'service'
+  | 'unknown';
+
+export interface VoicePipelineErrorInit {
+  kind: 'stt' | 'tts' | 'transport';
+  provider: string;
+  errorClass: HealthErrorClass;
+  message: string;
+  cause?: unknown;
+  retryable: boolean;
+}
+
+export class VoicePipelineError extends Error {
+  readonly kind: VoicePipelineErrorInit['kind'];
+  readonly provider: string;
+  readonly errorClass: HealthErrorClass;
+  readonly retryable: boolean;
+  readonly cause?: unknown;
+
+  constructor(init: VoicePipelineErrorInit) {
+    super(init.message);
+    this.name = 'VoicePipelineError';
+    this.kind = init.kind;
+    this.provider = init.provider;
+    this.errorClass = init.errorClass;
+    this.retryable = init.retryable;
+    this.cause = init.cause;
+  }
+
+  /**
+   * Best-effort classification of an arbitrary error into a voice-pipeline
+   * error with a well-known errorClass. Preserves the original error as
+   * `cause` so upstream inspection can still recover provider-specific
+   * detail.
+   */
+  static classifyError(
+    err: unknown,
+    meta: { kind: VoicePipelineErrorInit['kind']; provider: string }
+  ): VoicePipelineError {
+    const raw = err instanceof Error ? err : new Error(String(err));
+    const msg = raw.message ?? '';
+    const code = (err as { code?: string } | null)?.code ?? '';
+
+    let errorClass: HealthErrorClass = 'unknown';
+    let retryable = true;
+
+    if (/\b401\b|unauthori[sz]ed|invalid api key|forbidden|\b403\b/i.test(msg)) {
+      errorClass = 'auth';
+      retryable = false;
+    } else if (/\b429\b|rate.?limit|too many/i.test(msg)) {
+      errorClass = 'quota';
+      retryable = true;
+    } else if (/\b5\d\d\b|internal server|bad gateway|gateway timeout|service unavailable/i.test(msg)) {
+      errorClass = 'service';
+      retryable = true;
+    } else if (
+      code === 'ECONNRESET' ||
+      code === 'ETIMEDOUT' ||
+      code === 'ENOTFOUND' ||
+      /econnreset|etimedout|enotfound|socket hang up|network/i.test(msg)
+    ) {
+      errorClass = 'network';
+      retryable = true;
+    }
+
+    return new VoicePipelineError({
+      kind: meta.kind,
+      provider: meta.provider,
+      errorClass,
+      message: msg || 'unknown voice pipeline error',
+      cause: err,
+      retryable,
+    });
+  }
+}
+
+/**
+ * Aggregate thrown by `StreamingSTTChain` / `StreamingTTSChain` when every
+ * candidate provider fails. Carries the per-provider error list so callers
+ * can display a breakdown rather than a single confusing message.
+ */
+export class AggregateVoiceError extends Error {
+  readonly attempts: VoicePipelineError[];
+
+  constructor(attempts: VoicePipelineError[]) {
+    const summary = attempts
+      .map((a) => `${a.provider}: ${a.errorClass} \u2014 ${a.message}`)
+      .join('; ');
+    super(`All ${attempts.length} providers failed \u2014 ${summary}`);
+    this.name = 'AggregateVoiceError';
+    this.attempts = attempts;
+  }
+}

src/voice-pipeline/__tests__/VoicePipelineError.spec.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from 'vitest';
+import {
+  VoicePipelineError,
+  AggregateVoiceError,
+  type HealthErrorClass,
+} from '../VoicePipelineError.js';
+
+describe('VoicePipelineError', () => {
+  it('carries structured fields and a cause', () => {
+    const cause = new Error('upstream');
+    const err = new VoicePipelineError({
+      kind: 'stt',
+      provider: 'deepgram',
+      errorClass: 'auth',
+      message: 'invalid api key',
+      cause,
+      retryable: false,
+    });
+
+    expect(err.kind).toBe('stt');
+    expect(err.provider).toBe('deepgram');
+    expect(err.errorClass).toBe('auth');
+    expect(err.retryable).toBe(false);
+    expect(err.cause).toBe(cause);
+    expect(err.message).toBe('invalid api key');
+    expect(err).toBeInstanceOf(Error);
+    expect(err.name).toBe('VoicePipelineError');
+  });
+
+  it('classifyError maps common error shapes', () => {
+    const auth = VoicePipelineError.classifyError(
+      new Error('401 Unauthorized'),
+      { kind: 'stt', provider: 'deepgram' }
+    );
+    expect(auth.errorClass).toBe('auth');
+    expect(auth.retryable).toBe(false);
+
+    const quota = VoicePipelineError.classifyError(
+      new Error('429 Too Many Requests'),
+      { kind: 'tts', provider: 'elevenlabs' }
+    );
+    expect(quota.errorClass).toBe('quota');
+    expect(quota.retryable).toBe(true);
+
+    const network = VoicePipelineError.classifyError(
+      Object.assign(new Error('ECONNRESET'), { code: 'ECONNRESET' }),
+      { kind: 'stt', provider: 'deepgram' }
+    );
+    expect(network.errorClass).toBe('network');
+    expect(network.retryable).toBe(true);
+
+    const service = VoicePipelineError.classifyError(
+      new Error('500 Internal Server Error'),
+      { kind: 'tts', provider: 'openai-realtime' }
+    );
+    expect(service.errorClass).toBe('service');
+    expect(service.retryable).toBe(true);
+
+    const unknown = VoicePipelineError.classifyError(
+      new Error('something weird'),
+      { kind: 'stt', provider: 'deepgram' }
+    );
+    expect(unknown.errorClass).toBe('unknown');
+  });
+});
+
+describe('AggregateVoiceError', () => {
+  it('summarizes per-provider attempts', () => {
+    const attempts: VoicePipelineError[] = [
+      new VoicePipelineError({
+        kind: 'stt',
+        provider: 'deepgram',
+        errorClass: 'auth',
+        message: 'invalid key',
+        retryable: false,
+      }),
+      new VoicePipelineError({
+        kind: 'stt',
+        provider: 'elevenlabs',
+        errorClass: 'network',
+        message: 'ECONNRESET',
+        retryable: true,
+      }),
+    ];
+    const agg = new AggregateVoiceError(attempts);
+    expect(agg.attempts).toHaveLength(2);
+    expect(agg.name).toBe('AggregateVoiceError');
+    expect(agg.message).toContain('deepgram');
+    expect(agg.message).toContain('elevenlabs');
+    expect(agg.message).toContain('auth');
+  });
+});
+
+// Compile-time check that HealthErrorClass is exported and usable.
+const _typeCheck: HealthErrorClass = 'auth';
+void _typeCheck;