Claude API 音声エージェント本番アーキテクチャ構築ガイド

// 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 // Whisperは期間を返さないため別途計測
      };
    } 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 || 'ja';
    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;
            // interim_resultsが有効な場合、リアルタイム結果を送信
          }
        })
        .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> {
    // 直近のメッセージのみ保持（トークン効率化）
    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
        },
        // 第 2 引数のリクエストオプションに signal を渡すと、
        // 割り込みで畳んだターンの生成をその場で止められます。
        { signal: options.signal }
      );
 
      // content[0] を決め打ちにしない。thinking やツール使用を足した瞬間に、
      // 先頭が 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); // UI更新用
        }
      }
 
      return fullResponse;
    } catch (error) {
      console.error('Claude streaming failed:', error);
      throw new Error(`Streaming response failed: ${error.message}`);
    }
  }
}

const VOICE_AGENT_SYSTEM_PROMPT = `あなたは親切で自然な日本語で話す音声アシスタントです。
 
【基本指針】
- 簡潔で明確な日本語で応答してください。長い説明は避けてください。
- 敬語を自然に使い、ユーザーに尊重の気持ちを込めてください。
- 不確実な情報は「わかりません」と正直に答えてください。
- 音声出力されることを想定し、句読点は適切に付けてください。
 
【会話スタイル】
- 一文は60文字以下を目安にしてください。
- 複雑な情報は箇条書きで整理してください。
- 絵文字は使わないでください。
- 「です・ます」体で統一してください。`;

// 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';
import * as fs from 'fs';
 
export class GoogleCloudTTS implements TTSProvider {
  private client: textToSpeech.TextToSpeechClient;
  private projectId: string;
 
  constructor(projectId: string) {
    this.client = new textToSpeech.TextToSpeechClient();
    this.projectId = projectId;
  }
 
  async synthesize(text: string, voice = 'ja-JP-Neural2-B'): Promise<TTSResponse> {
    const request = {
      input: { text },
      voice: {
        languageCode: 'ja-JP',
        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;
 
      // 推定再生時間（平均120文字/分）
      const duration = (text.length / 120) * 60;
 
      return {
        audioBuffer,
        audioUrl: '', // S3アップロード後のURL
        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('ja-JP'))
      .map(v => v.name!) || [];
  }
 
  estimateDuration(text: string): number {
    return (text.length / 120) * 60;
  }
}
 
// ElevenLabsの実装（低遅延・高品質音声）
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 duration = (text.length / 120) * 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 {
    return (text.length / 120) * 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日間
 
  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);
 
    // キャッシュを確認
    const cached = await this.redis.getBuffer(key);
    if (cached) {
      console.log(`TTSCache HIT: ${key}`);
      return {
        audioBuffer: cached,
        audioUrl: '',
        duration: provider.estimateDuration(text),
        format: 'mp3'
      };
    }
 
    // TTSを実行
    console.log(`TTSCache MISS: ${key} - synthesizing...`);
    const result = await provider.synthesize(text, voice);
 
    // キャッシュに保存
    if (result.audioBuffer) {
      await this.redis.setex(
        key,
        this.ttlSeconds,
        result.audioBuffer
      );
    }
 
    return result;
  }
 
  async invalidate(text: string, voice: string, provider: string): Promise<void> {
    const key = this.generateKey(text, voice, provider);
    await this.redis.del(key);
  }
}

// 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[] = [];
 
  // セッションごとに 1 本だけ持つ直列チェーン。履歴の書き換えはこの中だけで行います。
  private chain: Promise<void> = Promise.resolve();
  // いま処理中のターン。次のフレームが来たらここを abort します（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`);
 
    // ハンドラ自体は同期。await を書かないので ws 側の発火順と処理順がずれません。
    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 in session ${this.sessionConfig.sessionId}:`,
        toMessage(error)
      );
    });
  }
 
  private async runTurn(ws: WebSocket, audioChunk: Buffer, signal: AbortSignal): Promise<void> {
    if (signal.aborted) return;  // 並び終わる前に次の発話で追い越された
 
    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;
 
      // 中断されずにここまで来たターンだけを履歴へ積みます。
      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 由来の例外はユーザーへ返さない
      console.error('Stream processing error:', error);
      ws.send(JSON.stringify({ type: 'error', message: toMessage(error) }));
    }
  }
 
  private async transcribeAudioChunk(audioData: Buffer): Promise<string> {
    // 実装は前述のDeepgramStreamingSTT参照
    return '';
  }
 
  private async generateSpeech(text: string): Promise<Buffer> {
    // TTSキャッシュを使用して音声を生成
    // 実装は前述のTTSCache参照
    return Buffer.alloc(0);
  }
 
  private cleanupSession(): void {
    this.conversationHistory = [];
    console.log(`Cleaned up session ${this.sessionConfig.sessionId}`);
  }
}

// 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);
  }
}

// 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) => {          // ← async を直接渡す（元の形）
  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, QueryResult } 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;
    preferredTopics: string[];
  };
}
 
export class UserContextManager {
  private userProfiles: Map<string, UserProfile> = new Map();
 
  async loadUserProfile(userId: string): Promise<UserProfile> {
    // DBから読み込み
    return {
      userId,
      name: 'User',
      preferences: {
        language: 'ja',
        voiceGender: 'female',
        formality: 'formal'
      },
      interactionHistory: {
        totalSessions: 0,
        averageSessionLength: 0,
        preferredTopics: []
      }
    };
  }
 
  buildSystemPromptWithContext(basePrompt: string, profile: UserProfile): string {
    return `${basePrompt}
 
【ユーザー情報】
- 名前: ${profile.name}
- 話し方の丁寧さ: ${profile.preferences.formality === 'formal' ? '敬語を使用' : 'ラフでもOK'}
- これまでのセッション数: ${profile.interactionHistory.totalSessions}
- 関心分野: ${profile.interactionHistory.preferredTopics.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, 'Audio processing failed. Please try again.');
  }
}
 
export class ClaudeAPIError extends VoiceAgentError {
  constructor(message: string, retryable = true) {
    super('CLAUDE_API_ERROR', message, retryable, 'I had trouble understanding. Could you repeat that?');
  }
}
 
export class TTSError extends VoiceAgentError {
  constructor(message: string, retryable = true) {
    super('TTS_ERROR', message, retryable, 'I cannot generate audio at this moment.');
  }
}
 
// エラー処理ミドルウェア
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 || 'An error occurred. Please try again.'
      };
    }
 
    // 予期しないエラー
    return {
      message: 'Unexpected error',
      fallback: 'Something went wrong. Please restart the session.'
    };
  }
}

// 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;
}
 
// 複数TTSプロバイダーのフォールバック
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; // 成功したプロバイダーを優先
        return result;
      } catch (error) {
        console.warn(`${name} failed: ${error.message}`);
        if (i === this.providers.length - 1) {
          throw new TTSError('All TTS providers failed');
        }
      }
    }
 
    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
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: voice-agent-secrets
              key: database-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', 'tts-elevenlabs'
  inputUnits: number; // トークン数、分数など
  outputUnits: number;
  costUSD: number;
  timestamp: Date;
}
 
export class CostTracker {
  private cloudwatch: CloudWatch;
  private costs: APICost[] = [];
 
  constructor() {
    this.cloudwatch = new CloudWatch();
  }
 
  // 単価は 2026-08-30 時点の公式価格ページ（USD / MTok）。
  // 計測側にリテラルを散らすと、世代交代のたびに直す場所を探すことになります。
  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;
 
  // usage をそのまま渡す。input_tokens にキャッシュ分は含まれないため、
  // 読み出し・書き込みを足さないと請求額より小さい数字が出ます。
  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;
 
    // キャッシュ読み出しは入力単価の 0.1 倍、5分書き込みは 1.25 倍
    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/分
    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 {
    // Google Cloud TTS: $16/MTok (100万文字)
    // ElevenLabs: $0.30/1万文字
    let cost = 0;
    if (provider === 'google') {
      cost = (characters / 1_000_000) * 16;
    } else if (provider === 'elevenlabs') {
      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 voice agent 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: 'Voice agent session duration',
    buckets: [10, 30, 60, 300, 600]
  }),
 
  apiLatencyMs: new prom.Histogram({
    name: 'voice_agent_api_latency_ms',
    help: 'API call latency',
    labelNames: ['service'],
    buckets: [50, 100, 200, 500, 1000, 2000]
  }),
 
  // ゲージ
  activeSessions: new prom.Gauge({
    name: 'voice_agent_active_sessions',
    help: 'Number of active sessions'
  }),
 
  queueLength: new prom.Gauge({
    name: 'voice_agent_queue_length',
    help: 'Length of pending requests',
    labelNames: ['service']
  })
};
 
// メトリクス記録ヘルパー
export function recordSessionMetric(
  durationSeconds: number,
  success: boolean
): void {
  voiceAgentMetrics.totalSessions.inc({ status: success ? 'success' : 'failed' });
  voiceAgentMetrics.sessionDurationSeconds.observe(durationSeconds);
}

// 実測ベースのレイテンシ予算チェッカー
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) {
    // Sentry に送る — 1セッションでも超過したら次の最適化候補
    console.warn(`[budget-exceeded] session=${sessionId} total=${total}ms`, b);
  }
  return total <= 1500;
}

// Cloudflare Workers 側のサインドトークン発行（Cloud Run の WebSocket は受信時に検証）
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);
}

// クライアント: VAD が発話開始を検知したら、まずローカル再生を殺す
export function createBargeInController(ws: WebSocket) {
  let current: AudioBufferSourceNode | null = null;
 
  return {
    play(node: AudioBufferSourceNode) {
      current = node;
      node.start();
    },
    onUserSpeechStart() {
      current?.stop();  // ① 先にローカル再生を即停止（20ms 以内）
      current = null;
      ws.send(JSON.stringify({ type: 'barge_in' }));  // ② その後にサーバへ通知
    },
  };
}

// 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;
 
// fastInput を持つモデルだけを抽出する。今は '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,          // ← Sonnet や Haiku を渡すと型エラー
  messages: Anthropic.MessageParam[],
  system: string
) {
  return client.messages.create({
    model,
    speed: 'fast',
    max_tokens: 512,
    system,
    messages,
  });
}

// 約束ラインを「起きる／朝に見る／週次で見る」の3段に割り当てる判定関数
type Severity = 'page' | 'morning' | 'weekly' | 'ok';
 
interface WindowStat {
  p95LatencyMs: number;      // 直近15分の p95
  costPerSession: number;    // 直近1時間の平均（USD）
  sessions: number;          // 母数。少なすぎる窓は判定しない
}
 
const LINE = { p95Ms: 1500, costUsd: 0.015 };
 
export function classify(w: WindowStat): Severity {
  if (w.sessions < 30) return 'ok';                       // 少数サンプルで起こさない
  if (w.p95LatencyMs > LINE.p95Ms * 1.2) return 'page';   // 体感が明確に悪化している
  if (w.costPerSession > LINE.costUsd * 2) return 'page'; // 課金の暴走は一晩で効いてくる
  if (w.p95LatencyMs > LINE.p95Ms) return 'morning';      // 約束ラインを越えた程度なら朝で足りる
  if (w.costPerSession > LINE.costUsd) return 'weekly';
  return 'ok';
}