Production Voice Agents with Claude API: Latency Budgets, Cost, and Fallbacks

// src/services/stt/whisper.ts
import FormData from 'form-data';
import fs from 'fs';
 
interface WhisperResponse {
  text: string;
  language: string;
  duration: number;
}
 
export class WhisperSTTService {
  private apiKey: string;
  private apiUrl = 'https://api.openai.com/v1/audio/transcriptions';
 
  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }
 
  async transcribe(audioPath: string, language?: string): Promise<WhisperResponse> {
    const form = new FormData();
    form.append('file', fs.createReadStream(audioPath));
    form.append('model', 'whisper-1');
 
    if (language) {
      form.append('language', language);
    }
 
    try {
      const response = await fetch(this.apiUrl, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          ...form.getHeaders()
        },
        body: form
      });
 
      const data = await response.json();
 
      if (!response.ok) {
        throw new Error(`Whisper API error: ${data.error?.message}`);
      }
 
      return {
        text: data.text,
        language: data.language || 'unknown',
        duration: 0
      };
    } catch (error) {
      console.error('Whisper transcription failed:', error);
      throw new Error(`STT processing failed: ${error.message}`);
    }
  }
}

// src/services/stt/deepgram-streaming.ts
import { createClient } from '@deepgram/sdk';
import { PassThrough } from 'stream';
 
interface StreamingSTTConfig {
  apiKey: string;
  language?: string;
  model?: string;
}
 
export class DeepgramStreamingSTT {
  private client: ReturnType<typeof createClient>;
  private language: string;
  private model: string;
 
  constructor(config: StreamingSTTConfig) {
    this.client = createClient(config.apiKey);
    this.language = config.language || 'en';
    this.model = config.model || 'nova-2';
  }
 
  async transcribeStream(audioStream: PassThrough): Promise<string> {
    return new Promise((resolve, reject) => {
      let finalTranscript = '';
 
      const connection = this.client.listen.live({
        model: this.model,
        language: this.language,
        punctuate: true,
        interim_results: true
      });
 
      connection
        .on('open', () => {
          console.log('Deepgram connection opened');
          audioStream.pipe(connection);
        })
        .on('results', (data) => {
          const transcript = data.result?.results?.[0]?.alternatives?.[0]?.transcript;
          if (transcript) {
            finalTranscript = transcript;
            // Emit interim_results to UI if needed
          }
        })
        .on('close', () => {
          resolve(finalTranscript);
        })
        .on('error', (error) => {
          reject(new Error(`Deepgram error: ${error.message}`));
        });
 
      audioStream.on('end', () => {
        connection.finish();
      });
    });
  }
}

// src/services/claude-agent.ts
import Anthropic from '@anthropic-ai/sdk';
 
interface ConversationMessage {
  role: 'user' | 'assistant';
  content: string;
}
 
interface VoiceAgentConfig {
  apiKey: string;
  systemPrompt: string;
  maxContextMessages?: number;
  temperature?: number;
}
 
export class VoiceAgent {
  private client: Anthropic;
  private systemPrompt: string;
  private maxContextMessages: number;
  private temperature: number;
 
  constructor(config: VoiceAgentConfig) {
    this.client = new Anthropic({ apiKey: config.apiKey });
    this.systemPrompt = config.systemPrompt;
    this.maxContextMessages = config.maxContextMessages || 10;
    this.temperature = config.temperature || 0.7;
  }
 
  async generateResponse(
    userInput: string,
    conversationHistory: ConversationMessage[],
    options: { signal?: AbortSignal } = {}
  ): Promise<string> {
    // Keep only recent messages to optimize token usage
    const recentHistory = conversationHistory.slice(-this.maxContextMessages);
 
    const messages = [
      ...recentHistory,
      { role: 'user' as const, content: userInput }
    ];
 
    try {
      const response = await this.client.messages.create(
        {
          model: 'claude-sonnet-5',
          max_tokens: 1024,
          temperature: this.temperature,
          system: this.systemPrompt,
          messages
        },
        // Request options take a signal, so a turn folded by barge-in
        // stops generating instead of billing to the end.
        { signal: options.signal }
      );
 
      // Don't hardcode content[0]: add thinking or tool use and the first
      // block stops being text.
      const textBlock = response.content.find(
        (block): block is Extract<typeof block, { type: 'text' }> => block.type === 'text'
      );
      if (!textBlock) {
        throw new Error('No text block in Claude response');
      }
 
      return textBlock.text;
    } catch (error: unknown) {
      console.error('Claude API call failed:', error);
      throw new Error(`Response generation failed: ${toMessage(error)}`);
    }
  }
 
  async generateResponseStream(
    userInput: string,
    conversationHistory: ConversationMessage[],
    onChunk: (chunk: string) => void
  ): Promise<string> {
    const recentHistory = conversationHistory.slice(-this.maxContextMessages);
 
    const messages = [
      ...recentHistory,
      { role: 'user' as const, content: userInput }
    ];
 
    let fullResponse = '';
 
    try {
      const stream = await this.client.messages.stream({
        model: 'claude-sonnet-5',
        max_tokens: 1024,
        temperature: this.temperature,
        system: this.systemPrompt,
        messages
      });
 
      for await (const chunk of stream) {
        if (chunk.type === 'content_block_delta' && chunk.delta?.type === 'text_delta') {
          const text = chunk.delta.text;
          fullResponse += text;
          onChunk(text); // Stream to client
        }
      }
 
      return fullResponse;
    } catch (error) {
      console.error('Claude streaming failed:', error);
      throw new Error(`Streaming response failed: ${error.message}`);
    }
  }
}

const VOICE_AGENT_SYSTEM_PROMPT = `You are a helpful, conversational voice assistant.
 
Guidelines:
- Respond naturally, as if speaking to someone. Keep sentences short (under 20 words when possible).
- Use conversational language. Avoid jargon unless the user introduced it first.
- If unsure, admit it. Don't speculate.
- Break complex information into bullet points (max 3 items per response).
- No emojis. No markdown formatting. Speak like a real person.
- Be warm and encouraging while remaining professional.`;

// src/services/tts/tts-provider.ts
export interface TTSResponse {
  audioUrl: string;
  audioBuffer?: Buffer;
  duration: number;
  format: 'mp3' | 'wav' | 'ogg';
}
 
export interface TTSProvider {
  synthesize(text: string, voice?: string): Promise<TTSResponse>;
  getAvailableVoices(): Promise<string[]>;
  estimateDuration(text: string): number;
}
 
// Google Cloud Text-to-Speech
import textToSpeech from '@google-cloud/text-to-speech';
 
export class GoogleCloudTTS implements TTSProvider {
  private client: textToSpeech.TextToSpeechClient;
 
  constructor() {
    this.client = new textToSpeech.TextToSpeechClient();
  }
 
  async synthesize(text: string, voice = 'en-US-Neural2-C'): Promise<TTSResponse> {
    const request = {
      input: { text },
      voice: {
        languageCode: 'en-US',
        name: voice
      },
      audioConfig: {
        audioEncoding: 'MP3' as const,
        pitch: 0,
        speakingRate: 1.0
      }
    };
 
    try {
      const [response] = await this.client.synthesizeSpeech(request);
      const audioBuffer = response.audioContent as Buffer;
 
      // Estimate duration: ~150 WPM average
      const words = text.split(/\s+/).length;
      const duration = (words / 150) * 60;
 
      return {
        audioBuffer,
        audioUrl: '',
        duration,
        format: 'mp3'
      };
    } catch (error) {
      throw new Error(`Google Cloud TTS failed: ${error.message}`);
    }
  }
 
  async getAvailableVoices(): Promise<string[]> {
    const [result] = await this.client.listVoices({});
    return result.voices
      ?.filter(v => v.languageCodes?.includes('en-US'))
      .map(v => v.name!) || [];
  }
 
  estimateDuration(text: string): number {
    const words = text.split(/\s+/).length;
    return (words / 150) * 60;
  }
}
 
// ElevenLabs for natural, expressive voices
import ElevenLabs from 'elevenlabs-node';
 
export class ElevenLabsTTS implements TTSProvider {
  private client: ElevenLabs;
  private voiceId: string;
 
  constructor(apiKey: string, voiceId: string) {
    this.client = new ElevenLabs({ apiKey });
    this.voiceId = voiceId;
  }
 
  async synthesize(text: string): Promise<TTSResponse> {
    try {
      const audioBuffer = await this.client.textToSpeech.convert({
        voice_id: this.voiceId,
        text,
        model_id: 'eleven_multilingual_v2',
        voice_settings: {
          stability: 0.5,
          similarity_boost: 0.75
        }
      });
 
      const words = text.split(/\s+/).length;
      const duration = (words / 150) * 60;
 
      return {
        audioBuffer: Buffer.from(audioBuffer),
        audioUrl: '',
        duration,
        format: 'mp3'
      };
    } catch (error) {
      throw new Error(`ElevenLabs TTS failed: ${error.message}`);
    }
  }
 
  async getAvailableVoices(): Promise<string[]> {
    const voices = await this.client.voices.getAll();
    return voices.map(v => v.voice_id);
  }
 
  estimateDuration(text: string): number {
    const words = text.split(/\s+/).length;
    return (words / 150) * 60;
  }
}

// src/services/tts/tts-cache.ts
import Redis from 'ioredis';
import crypto from 'crypto';
 
export class TTSCache {
  private redis: Redis;
  private ttlSeconds = 86400 * 30; // 30 days
 
  constructor(redisUrl: string) {
    this.redis = new Redis(redisUrl);
  }
 
  private generateKey(text: string, voice: string, provider: string): string {
    const hash = crypto
      .createHash('sha256')
      .update(`${text}:${voice}:${provider}`)
      .digest('hex');
    return `tts:${hash}`;
  }
 
  async getOrSynthesize(
    text: string,
    voice: string,
    provider: TTSProvider,
    providerName: string
  ): Promise<TTSResponse> {
    const key = this.generateKey(text, voice, providerName);
 
    // Check cache first
    const cached = await this.redis.getBuffer(key);
    if (cached) {
      console.log(`TTS cache hit: ${key}`);
      return {
        audioBuffer: cached,
        audioUrl: '',
        duration: provider.estimateDuration(text),
        format: 'mp3'
      };
    }
 
    // Synthesize and cache
    console.log(`TTS cache miss: ${key}`);
    const result = await provider.synthesize(text, voice);
 
    if (result.audioBuffer) {
      await this.redis.setex(
        key,
        this.ttlSeconds,
        result.audioBuffer
      );
    }
 
    return result;
  }
}

// src/websocket/voice-agent-handler.ts
import WebSocket from 'ws';
import { VoiceAgent } from '../services/claude-agent';
import { DeepgramStreamingSTT } from '../services/stt/deepgram-streaming';
import { TTSCache } from '../services/tts/tts-cache';
 
interface StreamingSessionConfig {
  sessionId: string;
  userId: string;
  voiceAgent: VoiceAgent;
  sttService: DeepgramStreamingSTT;
  ttsCache: TTSCache;
}
 
type Turn = { role: 'user' | 'assistant'; content: string };
 
export class VoiceAgentStreamHandler {
  private sessionConfig: StreamingSessionConfig;
  private conversationHistory: Turn[] = [];
 
  // One chain per session. History is only ever mutated inside it.
  private chain: Promise<void> = Promise.resolve();
  // The turn currently in flight. A new frame aborts it (barge-in).
  private current: AbortController | null = null;
 
  constructor(config: StreamingSessionConfig) {
    this.sessionConfig = config;
  }
 
  async handleWebSocketConnection(ws: WebSocket): Promise<void> {
    console.log(`Session ${this.sessionConfig.sessionId} connected`);
 
    // The listener itself is synchronous, so arrival order survives.
    ws.on('message', (data: Buffer) => {
      this.current?.abort();
      const ac = new AbortController();
      this.current = ac;
 
      this.chain = this.chain.then(() => this.runTurn(ws, data, ac.signal));
    });
 
    ws.on('close', () => {
      console.log(`Session ${this.sessionConfig.sessionId} closed`);
      this.current?.abort();
      this.cleanupSession();
    });
 
    ws.on('error', (error: unknown) => {
      console.error(`WebSocket error: ${toMessage(error)}`);
    });
  }
 
  private async runTurn(ws: WebSocket, audioChunk: Buffer, signal: AbortSignal): Promise<void> {
    if (signal.aborted) return;  // superseded while it waited its turn
 
    try {
      const transcript = await this.transcribeAudioChunk(audioChunk);
      if (!transcript || signal.aborted) return;
 
      const response = await this.sessionConfig.voiceAgent.generateResponse(
        transcript,
        this.conversationHistory,
        { signal }
      );
      if (signal.aborted) return;
 
      // Only turns that survived to here get written to history.
      this.conversationHistory.push(
        { role: 'user', content: transcript },
        { role: 'assistant', content: response }
      );
 
      const audioBuffer = await this.generateSpeech(response);
      if (signal.aborted) return;
 
      ws.send(JSON.stringify({
        type: 'response',
        transcript,
        response,
        audioBuffer: audioBuffer.toString('base64')
      }));
    } catch (error: unknown) {
      if (signal.aborted) return;  // abort-driven rejections aren't user-facing
      console.error('Stream processing error:', error);
      ws.send(JSON.stringify({ type: 'error', message: toMessage(error) }));
    }
  }
 
  private async transcribeAudioChunk(audioData: Buffer): Promise<string> {
    // Integration with Deepgram streaming service
    return '';
  }
 
  private async generateSpeech(text: string): Promise<Buffer> {
    // Integration with TTS cache service
    return Buffer.alloc(0);
  }
 
  private cleanupSession(): void {
    this.conversationHistory = [];
  }
}

// src/utils/to-message.ts
export function toMessage(error: unknown): string {
  if (error instanceof Error) return error.message;
  if (typeof error === 'string') return error;
  try {
    return JSON.stringify(error);
  } catch {
    return String(error);
  }
}

// Run on Node.js v22.23.2
import { EventEmitter } from 'node:events';
 
const em = new EventEmitter();
const history = [];
const generate = (t) => new Promise(r => setTimeout(() => r(`assistant:${t}`), 60 - t * 10));
 
em.on('message', async (t) => {          // the original shape
  const resp = await generate(t);
  history.push(`user:${t}`, resp);
});
 
for (const t of [1, 2, 3]) setTimeout(() => em.emit('message', t), t * 5);
setTimeout(() => console.log(JSON.stringify(history)), 300);

// src/db/session-repository.ts
import { Pool } from 'pg';
 
interface VoiceSession {
  sessionId: string;
  userId: string;
  startTime: Date;
  endTime?: Date;
  conversationHistory: Array<{ role: string; content: string }>;
  metadata: Record<string, any>;
}
 
export class VoiceSessionRepository {
  private pool: Pool;
 
  constructor(connectionString: string) {
    this.pool = new Pool({ connectionString });
  }
 
  async createSession(session: VoiceSession): Promise<void> {
    const query = `
      INSERT INTO voice_sessions (session_id, user_id, start_time, conversation_history, metadata)
      VALUES ($1, $2, $3, $4, $5)
    `;
 
    await this.pool.query(query, [
      session.sessionId,
      session.userId,
      session.startTime,
      JSON.stringify(session.conversationHistory),
      JSON.stringify(session.metadata)
    ]);
  }
 
  async updateConversation(
    sessionId: string,
    history: Array<{ role: string; content: string }>
  ): Promise<void> {
    const query = `
      UPDATE voice_sessions
      SET conversation_history = $1, updated_at = NOW()
      WHERE session_id = $2
    `;
 
    await this.pool.query(query, [JSON.stringify(history), sessionId]);
  }
 
  async getSession(sessionId: string): Promise<VoiceSession | null> {
    const query = `
      SELECT session_id, user_id, start_time, conversation_history, metadata
      FROM voice_sessions
      WHERE session_id = $1
    `;
 
    const result = await this.pool.query(query, [sessionId]);
    if (result.rows.length === 0) return null;
 
    const row = result.rows[0];
    return {
      sessionId: row.session_id,
      userId: row.user_id,
      startTime: row.start_time,
      conversationHistory: JSON.parse(row.conversation_history),
      metadata: JSON.parse(row.metadata)
    };
  }
 
  async endSession(sessionId: string): Promise<void> {
    const query = `
      UPDATE voice_sessions
      SET end_time = NOW()
      WHERE session_id = $1
    `;
 
    await this.pool.query(query, [sessionId]);
  }
}

// src/services/user-context.ts
export interface UserProfile {
  userId: string;
  name: string;
  preferences: {
    language: string;
    voiceGender: 'male' | 'female';
    formality: 'casual' | 'formal';
  };
  interactionHistory: {
    totalSessions: number;
    averageSessionLength: number;
    favoriteTopics: string[];
  };
}
 
export class UserContextManager {
  async loadUserProfile(userId: string): Promise<UserProfile> {
    // Load from database
    return {
      userId,
      name: 'User',
      preferences: {
        language: 'en',
        voiceGender: 'female',
        formality: 'formal'
      },
      interactionHistory: {
        totalSessions: 0,
        averageSessionLength: 0,
        favoriteTopics: []
      }
    };
  }
 
  buildSystemPromptWithContext(basePrompt: string, profile: UserProfile): string {
    return `${basePrompt}
 
User Context:
- Name: ${profile.name}
- Preferred formality: ${profile.preferences.formality}
- Previous sessions: ${profile.interactionHistory.totalSessions}
- Favorite topics: ${profile.interactionHistory.favoriteTopics.join(', ')}`;
  }
}

// src/error-handling/voice-agent-errors.ts
export class VoiceAgentError extends Error {
  constructor(
    public code: string,
    message: string,
    public retryable: boolean = false,
    public fallback?: string
  ) {
    super(message);
    this.name = 'VoiceAgentError';
  }
}
 
export class STTError extends VoiceAgentError {
  constructor(message: string, retryable = true) {
    super('STT_ERROR', message, retryable, 'I had trouble hearing you. Could you try again?');
  }
}
 
export class ClaudeAPIError extends VoiceAgentError {
  constructor(message: string, retryable = true) {
    super('CLAUDE_ERROR', message, retryable, 'I need a moment. Can you repeat that?');
  }
}
 
export class TTSError extends VoiceAgentError {
  constructor(message: string, retryable = true) {
    super('TTS_ERROR', message, retryable, 'I cannot generate audio right now.');
  }
}
 
// Error handling middleware
export class VoiceAgentErrorHandler {
  async handle(error: any, sessionId: string): Promise<{ message: string; fallback: string }> {
    console.error(`[${sessionId}] Error:`, error);
 
    if (error instanceof VoiceAgentError) {
      return {
        message: error.message,
        fallback: error.fallback || 'Something went wrong. Please try again.'
      };
    }
 
    return {
      message: 'Unexpected error',
      fallback: 'I encountered an issue. Let\'s start over.'
    };
  }
}

// src/resilience/retry-strategy.ts
export interface RetryConfig {
  maxAttempts: number;
  initialDelayMs: number;
  maxDelayMs: number;
  backoffMultiplier: number;
}
 
const DEFAULT_RETRY_CONFIG: RetryConfig = {
  maxAttempts: 3,
  initialDelayMs: 100,
  maxDelayMs: 5000,
  backoffMultiplier: 2
};
 
export async function withRetry<T>(
  fn: () => Promise<T>,
  config: RetryConfig = DEFAULT_RETRY_CONFIG
): Promise<T> {
  let lastError: Error | null = null;
  let delay = config.initialDelayMs;
 
  for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error as Error;
      console.warn(`Attempt ${attempt} failed: ${lastError.message}`);
 
      if (attempt < config.maxAttempts) {
        await new Promise(resolve => setTimeout(resolve, delay));
        delay = Math.min(delay * config.backoffMultiplier, config.maxDelayMs);
      }
    }
  }
 
  throw lastError;
}
 
// Multi-provider TTS fallback
export class TTSFallbackManager {
  private providers: Array<{ name: string; provider: TTSProvider }>;
  private primaryIndex = 0;
 
  constructor(providers: Array<{ name: string; provider: TTSProvider }>) {
    this.providers = providers;
  }
 
  async synthesizeWithFallback(text: string): Promise<TTSResponse> {
    for (let i = 0; i < this.providers.length; i++) {
      const index = (this.primaryIndex + i) % this.providers.length;
      const { name, provider } = this.providers[index];
 
      try {
        console.log(`Attempting TTS with ${name}...`);
        const result = await provider.synthesize(text);
        this.primaryIndex = index; // Promote successful provider
        return result;
      } catch (error) {
        console.warn(`${name} failed: ${error.message}`);
        if (i === this.providers.length - 1) {
          throw new TTSError('All TTS providers unavailable');
        }
      }
    }
 
    throw new TTSError('No TTS providers available');
  }
}

# k8s/voice-agent-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: voice-agent
spec:
  replicas: 3
  selector:
    matchLabels:
      app: voice-agent
  template:
    metadata:
      labels:
        app: voice-agent
    spec:
      containers:
      - name: voice-agent
        image: voice-agent:latest
        resources:
          requests:
            memory: "512Mi"
            cpu: "500m"
          limits:
            memory: "1Gi"
            cpu: "1000m"
        env:
        - name: CLAUDE_API_KEY
          valueFrom:
            secretKeyRef:
              name: voice-agent-secrets
              key: claude-api-key
        - name: DEEPGRAM_API_KEY
          valueFrom:
            secretKeyRef:
              name: voice-agent-secrets
              key: deepgram-api-key
        - name: REDIS_URL
          valueFrom:
            configMapKeyRef:
              name: voice-agent-config
              key: redis-url
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5
 
---
apiVersion: v1
kind: Service
metadata:
  name: voice-agent-service
spec:
  selector:
    app: voice-agent
  ports:
  - protocol: TCP
    port: 80
    targetPort: 3000
  type: LoadBalancer

// src/infra/session-affinity.ts
import Redis from 'ioredis';
 
export class SessionAffinityManager {
  private redis: Redis;
 
  constructor(redisUrl: string) {
    this.redis = new Redis(redisUrl);
  }
 
  async assignPodToSession(sessionId: string, podName: string): Promise<void> {
    await this.redis.setex(`session:affinity:${sessionId}`, 86400, podName);
  }
 
  async getPodForSession(sessionId: string): Promise<string | null> {
    return this.redis.get(`session:affinity:${sessionId}`);
  }
 
  async releaseSessionAffinity(sessionId: string): Promise<void> {
    await this.redis.del(`session:affinity:${sessionId}`);
  }
}

// src/monitoring/cost-tracker.ts
import { CloudWatch } from 'aws-sdk';
 
export interface APICost {
  service: string; // 'claude', 'whisper', 'tts-google', etc
  inputUnits: number; // tokens, minutes, characters
  outputUnits: number;
  costUSD: number;
  timestamp: Date;
}
 
export class CostTracker {
  private cloudwatch: CloudWatch;
  private costs: APICost[] = [];
 
  constructor() {
    this.cloudwatch = new CloudWatch();
  }
 
  // Rates as published on 2026-08-30 (USD / MTok).
  // Scattering literals through the metering code means hunting them down
  // every time a model generation turns over.
  private static readonly RATES = {
    'claude-opus-5': { input: 5, output: 25 },
    'claude-sonnet-5': { input: 2, output: 10 },
    'claude-haiku-4-5-20251001': { input: 1, output: 5 },
  } as const;
 
  // Pass `usage` straight through. `input_tokens` excludes cached tokens, so
  // skipping the cache fields produces a number smaller than your invoice.
  recordClaudeCall(
    model: keyof typeof CostTracker.RATES,
    usage: {
      input_tokens?: number;
      output_tokens?: number;
      cache_read_input_tokens?: number;
      cache_creation_input_tokens?: number;
    }
  ): void {
    const rate = CostTracker.RATES[model];
    const fresh = usage.input_tokens ?? 0;
    const cacheRead = usage.cache_read_input_tokens ?? 0;
    const cacheWrite = usage.cache_creation_input_tokens ?? 0;
    const out = usage.output_tokens ?? 0;
 
    // Cache reads bill at 0.1x the input rate; 5-minute writes at 1.25x.
    const costUSD =
      (fresh * rate.input +
        cacheRead * rate.input * 0.1 +
        cacheWrite * rate.input * 1.25 +
        out * rate.output) / 1_000_000;
 
    this.costs.push({
      service: `claude:${model}`,
      inputUnits: fresh + cacheRead + cacheWrite,
      outputUnits: out,
      costUSD,
      timestamp: new Date()
    });
  }
 
  recordWhisperCall(duration: number): void {
    // Whisper: $0.02/minute
    const cost = (duration / 60) * 0.02;
 
    this.costs.push({
      service: 'whisper',
      inputUnits: Math.ceil(duration),
      outputUnits: 0,
      costUSD: cost,
      timestamp: new Date()
    });
  }
 
  recordTTSCall(characters: number, provider: string): void {
    let cost = 0;
    if (provider === 'google') {
      // Google Cloud TTS: $16 per million characters
      cost = (characters / 1_000_000) * 16;
    } else if (provider === 'elevenlabs') {
      // ElevenLabs: $0.30 per 10,000 characters
      cost = (characters / 10_000) * 0.30;
    }
 
    this.costs.push({
      service: `tts-${provider}`,
      inputUnits: characters,
      outputUnits: 0,
      costUSD: cost,
      timestamp: new Date()
    });
  }
 
  async publishMetrics(sessionId: string): Promise<void> {
    const totalCost = this.costs.reduce((sum, c) => sum + c.costUSD, 0);
 
    await this.cloudwatch.putMetricData({
      Namespace: 'VoiceAgent',
      MetricData: [
        {
          MetricName: 'SessionCost',
          Value: totalCost,
          Unit: 'None',
          Dimensions: [{ Name: 'SessionId', Value: sessionId }]
        },
        {
          MetricName: 'APICallCount',
          Value: this.costs.length,
          Unit: 'Count'
        }
      ]
    }).promise();
 
    console.log(`Session ${sessionId} cost: $${totalCost.toFixed(4)}`);
  }
}

// src/monitoring/metrics.ts
import prom from 'prom-client';
 
export const voiceAgentMetrics = {
  totalSessions: new prom.Counter({
    name: 'voice_agent_total_sessions',
    help: 'Total number of sessions',
    labelNames: ['status'] // success, failed, timeout
  }),
 
  apiCallsTotal: new prom.Counter({
    name: 'voice_agent_api_calls_total',
    help: 'Total API calls by service',
    labelNames: ['service'] // claude, whisper, tts
  }),
 
  sessionDurationSeconds: new prom.Histogram({
    name: 'voice_agent_session_duration_seconds',
    help: 'Session duration in seconds',
    buckets: [10, 30, 60, 300, 600]
  }),
 
  apiLatencyMs: new prom.Histogram({
    name: 'voice_agent_api_latency_ms',
    help: 'API latency in milliseconds',
    labelNames: ['service'],
    buckets: [50, 100, 200, 500, 1000, 2000]
  }),
 
  activeSessions: new prom.Gauge({
    name: 'voice_agent_active_sessions',
    help: 'Number of currently active sessions'
  })
};
 
export function recordSessionMetric(durationSeconds: number, success: boolean): void {
  voiceAgentMetrics.totalSessions.inc({ status: success ? 'success' : 'failed' });
  voiceAgentMetrics.sessionDurationSeconds.observe(durationSeconds);
}

// Production budget checker — emit Sentry warnings on any over-budget session
interface LatencyBudget {
  stt: { budget: 600; actual?: number };
  llm: { budget: 400; actual?: number };
  tts: { budget: 400; actual?: number };
  network: { budget: 100; actual?: number };
}
 
export function assertBudget(b: LatencyBudget, sessionId: string) {
  const total = (b.stt.actual ?? 0) + (b.llm.actual ?? 0) +
                (b.tts.actual ?? 0) + (b.network.actual ?? 0);
  if (total > 1500) {
    console.warn(`[budget-exceeded] session=${sessionId} total=${total}ms`, b);
  }
  return total <= 1500;
}

// Workers issues a short-lived JWT; Cloud Run verifies it on WebSocket upgrade
import { SignJWT } from 'jose';
 
export async function issueVoiceSessionToken(env: Env, userId: string) {
  const secret = new TextEncoder().encode(env.VOICE_SESSION_SECRET);
  return await new SignJWT({ sub: userId, scope: 'voice-session' })
    .setProtectedHeader({ alg: 'HS256' })
    .setIssuedAt()
    .setExpirationTime('15m')
    .sign(secret);
}

// Client: when VAD fires, kill local playback first
export function createBargeInController(ws: WebSocket) {
  let current: AudioBufferSourceNode | null = null;
 
  return {
    play(node: AudioBufferSourceNode) {
      current = node;
      node.start();
    },
    onUserSpeechStart() {
      current?.stop();  // 1. silence locally, within ~20ms
      current = null;
      ws.send(JSON.stringify({ type: 'barge_in' }));  // 2. then tell the server
    },
  };
}

// src/services/model-policy.ts
const RATES = {
  'claude-opus-5': { input: 5, output: 25, fastInput: 10, fastOutput: 50 },
  'claude-sonnet-5': { input: 2, output: 10 },
  'claude-haiku-4-5-20251001': { input: 1, output: 5 },
} as const;
 
type ModelId = keyof typeof RATES;
 
// Narrows to the models that carry a fast rate — today, only 'claude-opus-5'
type FastCapable = {
  [K in ModelId]: 'fastInput' extends keyof (typeof RATES)[K] ? K : never;
}[ModelId];
 
export async function escalateFast(
  client: Anthropic,
  model: FastCapable,          // passing Sonnet or Haiku is a type error
  messages: Anthropic.MessageParam[],
  system: string
) {
  return client.messages.create({
    model,
    speed: 'fast',
    max_tokens: 512,
    system,
    messages,
  });
}

// Map the budget line onto three tiers: page / morning / weekly
type Severity = 'page' | 'morning' | 'weekly' | 'ok';
 
interface WindowStat {
  p95LatencyMs: number;      // p95 over the last 15 minutes
  costPerSession: number;    // last-hour average (USD)
  sessions: number;          // sample size; skip windows that are too small
}
 
const LINE = { p95Ms: 1500, costUsd: 0.015 };
 
export function classify(w: WindowStat): Severity {
  if (w.sessions < 30) return 'ok';                       // never wake me on a tiny sample
  if (w.p95LatencyMs > LINE.p95Ms * 1.2) return 'page';   // users clearly feel it
  if (w.costPerSession > LINE.costUsd * 2) return 'page'; // runaway spend compounds overnight
  if (w.p95LatencyMs > LINE.p95Ms) return 'morning';      // just over the line can wait until morning
  if (w.costPerSession > LINE.costUsd) return 'weekly';
  return 'ok';
}