@framers/agentos-ext-voice-synthesis 2.0.1 → 2.1.0

package/src/tools/textToSpeech.ts

@@ -1,287 +0,0 @@
-/**
- * Multi-provider TTS Tool — text-to-speech synthesis.
- *
- * Supports: OpenAI TTS, ElevenLabs, Ollama (local), any OpenAI-compatible TTS API.
- * Auto-detects available provider from API keys in environment.
- */
-
-import type { ITool, ToolExecutionContext, ToolExecutionResult, JSONSchemaObject } from '@framers/agentos';
-
-export type TTSProvider = 'openai' | 'elevenlabs' | 'ollama' | 'auto';
-
-export interface TTSInput {
-  text: string;
-  voice?: string;
-  model?: string;
-  provider?: TTSProvider;
-  /** ElevenLabs-specific */
-  stability?: number;
-  /** ElevenLabs-specific */
-  similarity_boost?: number;
-  /** OpenAI-specific: speed 0.25-4.0 */
-  speed?: number;
-  /** Output format: mp3, opus, aac, flac, wav */
-  format?: string;
-}
-
-export interface TTSOutput {
-  text: string;
-  voice: string;
-  model: string;
-  provider: string;
-  audioBase64: string;
-  contentType: string;
-  durationEstimateMs: number;
-}
-
-// ── ElevenLabs voice name → ID mapping ──
-const ELEVENLABS_VOICES: Record<string, string> = {
-  rachel: '21m00Tcm4TlvDq8ikWAM',
-  domi: 'AZnzlk1XvdvUeBnXmlld',
-  bella: 'EXAVITQu4vr4xnSDxMaL',
-  antoni: 'ErXwobaYiN019PkySvjV',
-  josh: 'TxGEqnHWrfWFTfGW9XjX',
-  arnold: 'VR6AewLTigWG4xSOukaG',
-  adam: 'pNInz6obpgDQGcFmaJgB',
-  sam: 'yoZ06aMxZJJ28mfd3POQ',
-};
-
-// ── OpenAI voice options ──
-const OPENAI_VOICES = ['alloy', 'echo', 'fable', 'onyx', 'nova', 'shimmer'];
-
-export interface TTSConfig {
-  openaiApiKey?: string;
-  openaiBaseUrl?: string;
-  elevenLabsApiKey?: string;
-  ollamaBaseUrl?: string;
-  defaultProvider?: TTSProvider;
-}
-
-export class TextToSpeechTool implements ITool<TTSInput, TTSOutput> {
-  readonly id = 'tts-multi-provider-v1';
-  readonly name = 'text_to_speech';
-  readonly displayName = 'Text to Speech';
-  readonly description =
-    'Convert text to speech audio. Supports multiple providers: OpenAI TTS (alloy/echo/fable/onyx/nova/shimmer), ' +
-    'ElevenLabs (rachel/domi/bella/antoni/josh/arnold/adam/sam), or local Ollama TTS. ' +
-    'Auto-detects available provider from API keys. Returns base64-encoded audio.';
-  readonly category = 'media';
-  readonly version = '2.0.0';
-  readonly hasSideEffects = false;
-
-  readonly inputSchema: JSONSchemaObject = {
-    type: 'object',
-    properties: {
-      text: { type: 'string', description: 'Text to convert to speech. Max 5000 chars.' },
-      voice: {
-        type: 'string',
-        description:
-          'Voice name. OpenAI: alloy, echo, fable, onyx, nova (default), shimmer. ' +
-          'ElevenLabs: rachel (default), domi, bella, antoni, josh, arnold, adam, sam. ' +
-          'Or a custom voice ID.',
-      },
-      model: {
-        type: 'string',
-        description: 'TTS model. OpenAI: tts-1 (default), tts-1-hd. ElevenLabs: eleven_monolingual_v1 (default), eleven_multilingual_v2.',
-      },
-      provider: {
-        type: 'string',
-        enum: ['openai', 'elevenlabs', 'ollama', 'auto'],
-        description: 'TTS provider. Default: auto (detects from available API keys).',
-      },
-      speed: { type: 'number', minimum: 0.25, maximum: 4.0, description: 'OpenAI speed multiplier (0.25-4.0).' },
-      stability: { type: 'number', minimum: 0, maximum: 1, description: 'ElevenLabs voice stability (0-1).' },
-      similarity_boost: { type: 'number', minimum: 0, maximum: 1, description: 'ElevenLabs similarity boost (0-1).' },
-      format: { type: 'string', enum: ['mp3', 'opus', 'aac', 'flac', 'wav'], description: 'Output audio format.' },
-    },
-    required: ['text'],
-  };
-
-  readonly requiredCapabilities = ['capability:tts'];
-
-  private config: TTSConfig;
-
-  constructor(config?: TTSConfig) {
-    this.config = {
-      openaiApiKey: config?.openaiApiKey || process.env.OPENAI_API_KEY || '',
-      openaiBaseUrl: config?.openaiBaseUrl || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
-      elevenLabsApiKey: config?.elevenLabsApiKey || process.env.ELEVENLABS_API_KEY || '',
-      ollamaBaseUrl: config?.ollamaBaseUrl || process.env.OLLAMA_BASE_URL || 'http://localhost:11434',
-      defaultProvider: config?.defaultProvider || (process.env.TTS_PROVIDER as TTSProvider) || 'auto',
-    };
-  }
-
-  private resolveProvider(requested?: TTSProvider): TTSProvider | null {
-    const pref = requested || this.config.defaultProvider || 'auto';
-    if (pref !== 'auto') {
-      // Verify the requested provider has credentials
-      if (pref === 'openai' && this.config.openaiApiKey) return 'openai';
-      if (pref === 'elevenlabs' && this.config.elevenLabsApiKey) return 'elevenlabs';
-      if (pref === 'ollama') return 'ollama';
-      // Fall through to auto if requested provider isn't configured
-    }
-
-    // Auto-detect: prefer OpenAI (cheaper, faster), then ElevenLabs, then Ollama
-    if (this.config.openaiApiKey) return 'openai';
-    if (this.config.elevenLabsApiKey) return 'elevenlabs';
-    return 'ollama'; // Local fallback — may or may not have TTS model
-  }
-
-  async execute(args: TTSInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<TTSOutput>> {
-    const text = args.text.slice(0, 5000);
-    const provider = this.resolveProvider(args.provider);
-
-    if (!provider) {
-      return {
-        success: false,
-        error:
-          'No TTS provider available. Set one of: OPENAI_API_KEY, ELEVENLABS_API_KEY, or configure Ollama with a TTS model. ' +
-          'Get an OpenAI key at https://platform.openai.com/api-keys or ElevenLabs at https://elevenlabs.io',
-      };
-    }
-
-    try {
-      switch (provider) {
-        case 'openai':
-          return await this.synthesizeOpenAI(text, args);
-        case 'elevenlabs':
-          return await this.synthesizeElevenLabs(text, args);
-        case 'ollama':
-          return await this.synthesizeOllama(text, args);
-        default:
-          return { success: false, error: `Unknown TTS provider: ${provider}` };
-      }
-    } catch (err: any) {
-      return { success: false, error: `TTS failed (${provider}): ${err.message}` };
-    }
-  }
-
-  // ── OpenAI TTS ──
-
-  private async synthesizeOpenAI(text: string, args: TTSInput): Promise<ToolExecutionResult<TTSOutput>> {
-    const voice = args.voice && OPENAI_VOICES.includes(args.voice) ? args.voice : 'nova';
-    const model = args.model || 'tts-1';
-    const format = args.format || 'mp3';
-
-    const response = await fetch(`${this.config.openaiBaseUrl}/audio/speech`, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${this.config.openaiApiKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        model,
-        voice,
-        input: text,
-        response_format: format,
-        speed: args.speed,
-      }),
-    });
-
-    if (!response.ok) {
-      const err = await response.text();
-      return { success: false, error: `OpenAI TTS error (${response.status}): ${err.slice(0, 300)}` };
-    }
-
-    const buf = await response.arrayBuffer();
-    const audioBase64 = Buffer.from(buf).toString('base64');
-    const contentType = format === 'opus' ? 'audio/opus' : format === 'wav' ? 'audio/wav' : 'audio/mpeg';
-    const durationEstimateMs = Math.round((text.split(/\s+/).length / 150) * 60 * 1000);
-
-    return {
-      success: true,
-      output: { text, voice, model, provider: 'openai', audioBase64, contentType, durationEstimateMs },
-      contentType,
-    };
-  }
-
-  // ── ElevenLabs TTS ──
-
-  private async synthesizeElevenLabs(text: string, args: TTSInput): Promise<ToolExecutionResult<TTSOutput>> {
-    const voiceId = ELEVENLABS_VOICES[(args.voice || 'rachel').toLowerCase()] || args.voice || ELEVENLABS_VOICES.rachel;
-    const model = args.model || 'eleven_monolingual_v1';
-
-    const response = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voiceId}`, {
-      method: 'POST',
-      headers: {
-        'xi-api-key': this.config.elevenLabsApiKey!,
-        'Content-Type': 'application/json',
-        Accept: 'audio/mpeg',
-      },
-      body: JSON.stringify({
-        text,
-        model_id: model,
-        voice_settings: {
-          stability: args.stability ?? 0.5,
-          similarity_boost: args.similarity_boost ?? 0.75,
-        },
-      }),
-    });
-
-    if (!response.ok) {
-      const err = await response.text();
-      return { success: false, error: `ElevenLabs error (${response.status}): ${err.slice(0, 300)}` };
-    }
-
-    const buf = await response.arrayBuffer();
-    const audioBase64 = Buffer.from(buf).toString('base64');
-    const durationEstimateMs = Math.round((text.split(/\s+/).length / 150) * 60 * 1000);
-
-    return {
-      success: true,
-      output: {
-        text,
-        voice: args.voice || 'rachel',
-        model,
-        provider: 'elevenlabs',
-        audioBase64,
-        contentType: 'audio/mpeg',
-        durationEstimateMs,
-      },
-      contentType: 'audio/mpeg',
-    };
-  }
-
-  // ── Ollama TTS (local, experimental) ──
-
-  private async synthesizeOllama(text: string, args: TTSInput): Promise<ToolExecutionResult<TTSOutput>> {
-    // Ollama doesn't natively support TTS yet, but some models (e.g., bark, piper)
-    // can be served via OpenAI-compatible endpoints. Try the OpenAI-compat path.
-    const voice = args.voice || 'default';
-    const model = args.model || 'tts'; // User must have a TTS model loaded
-
-    try {
-      const response = await fetch(`${this.config.ollamaBaseUrl}/v1/audio/speech`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ model, voice, input: text }),
-      });
-
-      if (!response.ok) {
-        return {
-          success: false,
-          error:
-            `Ollama TTS not available (${response.status}). Ollama doesn't natively support TTS yet. ` +
-            'Set OPENAI_API_KEY or ELEVENLABS_API_KEY for cloud TTS, or use a dedicated local TTS server.',
-        };
-      }
-
-      const buf = await response.arrayBuffer();
-      const audioBase64 = Buffer.from(buf).toString('base64');
-      const durationEstimateMs = Math.round((text.split(/\s+/).length / 150) * 60 * 1000);
-
-      return {
-        success: true,
-        output: { text, voice, model, provider: 'ollama', audioBase64, contentType: 'audio/mpeg', durationEstimateMs },
-        contentType: 'audio/mpeg',
-      };
-    } catch {
-      return {
-        success: false,
-        error:
-          'Ollama TTS endpoint not reachable. Ollama doesn\'t natively support TTS yet. ' +
-          'Set OPENAI_API_KEY or ELEVENLABS_API_KEY for cloud TTS.',
-      };
-    }
-  }
-}

package/test/textToSpeech.spec.ts

@@ -1,398 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-
-const mockFetch = vi.fn();
-vi.stubGlobal('fetch', mockFetch);
-
-// Clear env vars that affect provider detection
-const savedEnv: Record<string, string | undefined> = {};
-const envKeys = [
-  'OPENAI_API_KEY',
-  'ELEVENLABS_API_KEY',
-  'OPENAI_BASE_URL',
-  'OLLAMA_BASE_URL',
-  'TTS_PROVIDER',
-  'DEEPGRAM_API_KEY',
-  'DEEPGRAM_BASE_URL',
-  'WHISPER_LOCAL_BASE_URL',
-  'STT_PROVIDER',
-];
-
-const { TextToSpeechTool } = await import('../src/tools/textToSpeech.js');
-const { SpeechToTextTool } = await import('../src/tools/speechToText.js');
-const { createExtensionPack } = await import('../src/index.js');
-
-describe('TextToSpeechTool', () => {
-  const ctx = {} as any;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    // Save and clear env
-    for (const key of envKeys) {
-      savedEnv[key] = process.env[key];
-      delete process.env[key];
-    }
-  });
-
-  afterEach(() => {
-    // Restore env
-    for (const key of envKeys) {
-      if (savedEnv[key] !== undefined) process.env[key] = savedEnv[key];
-      else delete process.env[key];
-    }
-  });
-
-  describe('metadata', () => {
-    it('has correct id and name', () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: 'sk-test' });
-      expect(tool.id).toBe('tts-multi-provider-v1');
-      expect(tool.name).toBe('text_to_speech');
-    });
-
-    it('has valid input schema with text required', () => {
-      const tool = new TextToSpeechTool({});
-      expect(tool.inputSchema.type).toBe('object');
-      expect(tool.inputSchema.required).toContain('text');
-    });
-
-    it('has no side effects', () => {
-      const tool = new TextToSpeechTool({});
-      expect(tool.hasSideEffects).toBe(false);
-    });
-
-    it('describes multiple providers', () => {
-      const tool = new TextToSpeechTool({});
-      expect(tool.description).toContain('OpenAI');
-      expect(tool.description).toContain('ElevenLabs');
-    });
-  });
-
-  describe('provider resolution', () => {
-    it('falls back to Ollama when no API keys set', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: '', elevenLabsApiKey: '' });
-      mockFetch.mockRejectedValueOnce(new Error('ECONNREFUSED'));
-      const result = await tool.execute({ text: 'Hello' }, ctx);
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('Ollama');
-    });
-
-    it('auto-detects OpenAI when key provided', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: 'sk-test', elevenLabsApiKey: '' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(100) });
-      const result = await tool.execute({ text: 'Hello' }, ctx);
-      expect(result.success).toBe(true);
-      expect(result.output!.provider).toBe('openai');
-    });
-
-    it('auto-detects ElevenLabs when only that key set', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: '', elevenLabsApiKey: 'el-test' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(100) });
-      const result = await tool.execute({ text: 'Hello' }, ctx);
-      expect(result.success).toBe(true);
-      expect(result.output!.provider).toBe('elevenlabs');
-    });
-
-    it('respects explicit provider override', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: 'sk-test', elevenLabsApiKey: 'el-test' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(100) });
-      const result = await tool.execute({ text: 'Hello', provider: 'elevenlabs' }, ctx);
-      expect(result.success).toBe(true);
-      expect(result.output!.provider).toBe('elevenlabs');
-    });
-  });
-
-  describe('OpenAI TTS', () => {
-    it('synthesizes with default voice (nova)', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: 'sk-test', elevenLabsApiKey: '' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(100) });
-      const result = await tool.execute({ text: 'Hello world' }, ctx);
-      expect(result.success).toBe(true);
-      expect(result.output!.voice).toBe('nova');
-      expect(result.output!.provider).toBe('openai');
-      expect(result.output!.contentType).toBe('audio/mpeg');
-      expect(result.output!.audioBase64).toBeTruthy();
-    });
-
-    it('sends correct request to OpenAI API', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: 'sk-test', elevenLabsApiKey: '' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(10) });
-      await tool.execute({ text: 'Test', voice: 'shimmer', model: 'tts-1-hd' }, ctx);
-      const [url, opts] = mockFetch.mock.calls[0];
-      expect(url).toContain('/audio/speech');
-      const body = JSON.parse(opts.body);
-      expect(body.voice).toBe('shimmer');
-      expect(body.model).toBe('tts-1-hd');
-    });
-
-    it('handles API errors', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: 'sk-test', elevenLabsApiKey: '' });
-      mockFetch.mockResolvedValueOnce({ ok: false, status: 401, text: async () => 'Unauthorized' });
-      const result = await tool.execute({ text: 'Test' }, ctx);
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('401');
-    });
-  });
-
-  describe('ElevenLabs TTS', () => {
-    it('synthesizes with default voice (rachel)', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: '', elevenLabsApiKey: 'el-test' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(100) });
-      const result = await tool.execute({ text: 'Hello world' }, ctx);
-      expect(result.success).toBe(true);
-      expect(result.output!.voice).toBe('rachel');
-      expect(result.output!.provider).toBe('elevenlabs');
-    });
-
-    it('uses correct voice ID for named voice (josh)', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: '', elevenLabsApiKey: 'el-test' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(10) });
-      await tool.execute({ text: 'Test', voice: 'josh' }, ctx);
-      expect(mockFetch).toHaveBeenCalledWith(
-        expect.stringContaining('TxGEqnHWrfWFTfGW9XjX'),
-        expect.any(Object)
-      );
-    });
-
-    it('sends ElevenLabs API key header', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: '', elevenLabsApiKey: 'el-test' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(10) });
-      await tool.execute({ text: 'Test' }, ctx);
-      const [, opts] = mockFetch.mock.calls[0];
-      expect(opts.headers['xi-api-key']).toBe('el-test');
-    });
-  });
-
-  describe('common behavior', () => {
-    it('truncates text to 5000 chars', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: 'sk-test', elevenLabsApiKey: '' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(10) });
-      const result = await tool.execute({ text: 'a'.repeat(6000) }, ctx);
-      expect(result.success).toBe(true);
-      expect(result.output!.text.length).toBe(5000);
-    });
-
-    it('estimates duration from word count', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: 'sk-test', elevenLabsApiKey: '' });
-      mockFetch.mockResolvedValueOnce({ ok: true, arrayBuffer: async () => new ArrayBuffer(10) });
-      const result = await tool.execute({ text: 'one two three four five' }, ctx);
-      expect(result.success).toBe(true);
-      expect(result.output!.durationEstimateMs).toBeGreaterThan(0);
-    });
-
-    it('handles network errors gracefully', async () => {
-      const tool = new TextToSpeechTool({ openaiApiKey: 'sk-test', elevenLabsApiKey: '' });
-      mockFetch.mockRejectedValueOnce(new Error('ECONNREFUSED'));
-      const result = await tool.execute({ text: 'Test' }, ctx);
-      expect(result.success).toBe(false);
-      expect(result.error).toContain('TTS failed');
-    });
-  });
-});
-
-describe('createExtensionPack', () => {
-  it('creates pack with correct metadata', () => {
-    const pack = createExtensionPack({ options: { elevenLabsApiKey: 'test' }, logger: { info: vi.fn() } });
-    expect(pack.name).toBe('@framers/agentos-ext-voice-synthesis');
-    expect(pack.version).toBe('2.0.0');
-    expect(pack.descriptors).toHaveLength(2);
-    expect(pack.descriptors[0].kind).toBe('tool');
-    expect(pack.descriptors[0].id).toBe('text_to_speech');
-    expect(pack.descriptors[1].id).toBe('speech_to_text');
-  });
-});
-
-describe('SpeechToTextTool', () => {
-  const ctx = {} as any;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    for (const key of envKeys) {
-      savedEnv[key] = process.env[key];
-      delete process.env[key];
-    }
-  });
-
-  afterEach(() => {
-    for (const key of envKeys) {
-      if (savedEnv[key] !== undefined) process.env[key] = savedEnv[key];
-      else delete process.env[key];
-    }
-  });
-
-  it('has correct id and name', () => {
-    const tool = new SpeechToTextTool({ openaiApiKey: 'sk-test' });
-    expect(tool.id).toBe('stt-multi-provider-v1');
-    expect(tool.name).toBe('speech_to_text');
-    expect(tool.hasSideEffects).toBe(false);
-  });
-
-  it('fails when no provider is configured', async () => {
-    const tool = new SpeechToTextTool({ openaiApiKey: '' });
-    const result = await tool.execute({ audioBase64: Buffer.from('wav').toString('base64') }, ctx);
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('OPENAI_API_KEY');
-    expect(result.error).toContain('DEEPGRAM_API_KEY');
-  });
-
-  it('fails when no audio input is provided', async () => {
-    const tool = new SpeechToTextTool({ openaiApiKey: 'sk-test' });
-    const result = await tool.execute({}, ctx);
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('Provide either audioBase64 or audioUrl');
-  });
-
-  it('transcribes base64 audio through OpenAI Whisper', async () => {
-    const tool = new SpeechToTextTool({ openaiApiKey: 'sk-test' });
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      headers: { get: vi.fn().mockReturnValue('application/json') },
-      json: async () => ({ text: 'hello world', language: 'en', duration: 1.5, segments: [{ text: 'hello world', start: 0, end: 1.5 }] }),
-    });
-
-    const result = await tool.execute(
-      {
-        audioBase64: 'data:audio/wav;base64,' + Buffer.from('fake-audio').toString('base64'),
-        responseFormat: 'verbose_json',
-      },
-      ctx,
-    );
-
-    expect(result.success).toBe(true);
-    expect(result.output!.text).toBe('hello world');
-    expect(result.output!.language).toBe('en');
-    expect(result.output!.provider).toBe('openai');
-    expect(result.output!.segments).toHaveLength(1);
-    const [url, opts] = mockFetch.mock.calls[0];
-    expect(url).toContain('/audio/transcriptions');
-    expect(opts.headers.Authorization).toBe('Bearer sk-test');
-  });
-
-  it('auto-detects Deepgram when OpenAI is unavailable', async () => {
-    const tool = new SpeechToTextTool({ openaiApiKey: '', deepgramApiKey: 'dg-test' });
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      json: async () => ({
-        metadata: { duration: 2.1 },
-        results: {
-          utterances: [
-            {
-              transcript: 'hello from deepgram',
-              start: 0,
-              end: 2.1,
-              confidence: 0.98,
-              speaker: 0,
-              words: [{ word: 'hello', start: 0, end: 0.5, confidence: 0.9 }],
-            },
-          ],
-          channels: [
-            {
-              alternatives: [
-                {
-                  transcript: 'hello from deepgram',
-                  confidence: 0.98,
-                  detected_language: 'en',
-                },
-              ],
-            },
-          ],
-        },
-      }),
-    });
-
-    const result = await tool.execute(
-      {
-        audioBase64: Buffer.from('fake-audio').toString('base64'),
-      },
-      ctx,
-    );
-
-    expect(result.success).toBe(true);
-    expect(result.output!.provider).toBe('deepgram');
-    expect(result.output!.language).toBe('en');
-    expect(result.output!.segments).toHaveLength(1);
-    const [url, opts] = mockFetch.mock.calls[0];
-    expect(url).toContain('/listen?');
-    expect(opts.headers.Authorization).toBe('Token dg-test');
-  });
-
-  it('uses Whisper-local when explicitly requested', async () => {
-    const tool = new SpeechToTextTool({ whisperLocalBaseUrl: 'http://127.0.0.1:9000/v1' });
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      headers: { get: vi.fn().mockReturnValue('application/json') },
-      json: async () => ({
-        text: 'local transcript',
-        language: 'en',
-        duration: 1.2,
-      }),
-    });
-
-    const result = await tool.execute(
-      {
-        provider: 'whisper-local',
-        audioBase64: Buffer.from('fake-audio').toString('base64'),
-      },
-      ctx,
-    );
-
-    expect(result.success).toBe(true);
-    expect(result.output!.provider).toBe('whisper-local');
-    expect(result.output!.text).toBe('local transcript');
-    expect(mockFetch.mock.calls[0][0]).toContain('127.0.0.1:9000/v1/audio/transcriptions');
-  });
-
-  it('downloads audio from a URL before transcribing', async () => {
-    const tool = new SpeechToTextTool({ openaiApiKey: 'sk-test' });
-    mockFetch
-      .mockResolvedValueOnce({
-        ok: true,
-        headers: { get: vi.fn().mockReturnValue('audio/mpeg') },
-        arrayBuffer: async () => new ArrayBuffer(12),
-      })
-      .mockResolvedValueOnce({
-        ok: true,
-        headers: { get: vi.fn().mockReturnValue('text/plain') },
-        text: async () => 'remote transcript',
-      });
-
-    const result = await tool.execute({ audioUrl: 'https://example.com/audio.mp3', responseFormat: 'text' }, ctx);
-
-    expect(result.success).toBe(true);
-    expect(result.output!.text).toBe('remote transcript');
-    expect(mockFetch).toHaveBeenNthCalledWith(1, 'https://example.com/audio.mp3');
-    expect(mockFetch.mock.calls[1][0]).toContain('/audio/transcriptions');
-  });
-
-  it('surfaces download failures clearly', async () => {
-    const tool = new SpeechToTextTool({ openaiApiKey: 'sk-test' });
-    mockFetch.mockResolvedValueOnce({
-      ok: false,
-      status: 404,
-      headers: { get: vi.fn().mockReturnValue(null) },
-    });
-
-    const result = await tool.execute({ audioUrl: 'https://example.com/missing.wav' }, ctx);
-
-    expect(result.success).toBe(false);
-    expect(result.error).toContain('Audio download failed (404)');
-  });
-
-  it('respects STT_PROVIDER from the environment', async () => {
-    process.env.STT_PROVIDER = 'deepgram';
-    process.env.DEEPGRAM_API_KEY = 'dg-env';
-    const tool = new SpeechToTextTool({});
-    mockFetch.mockResolvedValueOnce({
-      ok: true,
-      json: async () => ({
-        metadata: { duration: 0.8 },
-        results: {
-          channels: [{ alternatives: [{ transcript: 'env transcript', confidence: 0.91 }] }],
-        },
-      }),
-    });
-
-    const result = await tool.execute({ audioBase64: Buffer.from('fake-audio').toString('base64') }, ctx);
-
-    expect(result.success).toBe(true);
-    expect(result.output!.provider).toBe('deepgram');
-  });
-});