@polpo-ai/tools 0.6.31 → 0.7.0

package/dist/audio-tools.js

@@ -1,39 +1,28 @@
 /**
  * Audio tools for speech-to-text (STT) and text-to-speech (TTS).
  *
- * Provides agent capabilities to:
- * - Transcribe audio files to text (audio_transcribe)
- * - Generate speech audio from text (audio_speak)
+ * Architecture: thin wrappers over the Vercel AI SDK v6.
+ *   - audio_transcribe → `experimental_transcribe`
+ *   - audio_speak      → `experimental_generateSpeech`
  *
- * Architecture: direct fetch() to provider REST APIs — zero vendor SDK dependencies.
+ * Model selection: each tool picks its model in this order:
+ *   1. per-call `model` input (`<provider>/<model>` string),
+ *   2. agent-config default (transcribe_model / tts_model),
+ *   3. DEFAULT_TRANSCRIBE_MODEL / DEFAULT_TTS_MODEL from @polpo-ai/core.
  *
- * Supported providers:
- *   STT: openai (Whisper), deepgram (Nova)
- *   TTS: openai (gpt-4o-mini-tts / tts-1), deepgram (Aura), elevenlabs, edge (free, local)
- *
- * Edge TTS: Uses Microsoft Edge's neural TTS engine via the `edge-tts` CLI.
- * Free, no API key, ~400 voices in 60+ languages. Auto-selects voice from
- * language + gender params. Also used as automatic fallback when cloud providers fail.
- * Install: `pip install edge-tts`
- *
- * Credential resolution order (same as email/image tools):
- *   1. Agent vault (per-agent credentials — e.g. service "openai" key "key")
- *   2. Environment variables (global fallback)
- *   3. Edge TTS (automatic fallback — no credentials needed)
- *
- * Environment variables (fallback):
- *   OPENAI_API_KEY    — openai provider (STT + TTS)
- *   DEEPGRAM_API_KEY  — deepgram provider (STT + TTS)
- *   ELEVENLABS_API_KEY — elevenlabs provider (TTS)
+ * audio_speak's `edge` provider is wrapped as a custom SpeechModelV3 in
+ * `lib/edge-speech-model.ts` so it slots into the same SDK call as
+ * cloud providers (no special-casing in the tool layer).
  */
 import { resolve, dirname, extname } from "node:path";
 import { Type } from "@sinclair/typebox";
+import { parseModelString, DEFAULT_TRANSCRIBE_MODEL, DEFAULT_TTS_MODEL, } from "@polpo-ai/core";
 import { NodeFileSystem } from "./adapters/node-filesystem.js";
 import { NodeShell } from "./adapters/node-shell.js";
 import { resolveAllowedPaths, assertPathAllowed } from "./path-sandbox.js";
+import { resolveTranscribeProvider, resolveSpeakProvider, } from "./lib/provider-resolver.js";
 // ─── Constants ───
 const MAX_AUDIO_SIZE = 25 * 1024 * 1024; // 25 MB (OpenAI Whisper limit)
-const DEFAULT_TIMEOUT = 120_000; // 2 min for audio processing
 // ─── Helpers ───
 function requireEnv(key) {
     const val = process.env[key];
@@ -41,54 +30,38 @@ function requireEnv(key) {
         throw new Error(`Missing environment variable: ${key}. Set it before using this tool.`);
     return val;
 }
-/** Build a FormData-like multipart body for fetch (Node 18+). */
-function audioFormData(fileBuffer, filename, fields) {
-    const form = new FormData();
-    const blob = new Blob([new Uint8Array(fileBuffer)], { type: mimeFromExt(extname(filename)) });
-    form.append("file", blob, filename);
-    for (const [k, v] of Object.entries(fields)) {
-        form.append(k, v);
-    }
-    return { body: form };
-}
-function mimeFromExt(ext) {
-    const map = {
-        ".mp3": "audio/mpeg",
-        ".wav": "audio/wav",
-        ".flac": "audio/flac",
-        ".ogg": "audio/ogg",
-        ".m4a": "audio/mp4",
-        ".webm": "audio/webm",
-        ".mp4": "audio/mp4",
-        ".mpeg": "audio/mpeg",
-        ".mpga": "audio/mpeg",
-    };
-    return map[ext.toLowerCase()] ?? "application/octet-stream";
+function resolveEffectiveModel(override, configured, fallback) {
+    return parseModelString(override ?? configured ?? fallback);
 }
+/** Default voices per TTS provider. Used when the input doesn't pass an explicit voice. */
+const SPEAK_DEFAULT_VOICES = {
+    openai: "alloy",
+    deepgram: undefined, // voice is encoded in the model id
+    elevenlabs: "21m00Tcm4TlvDq8ikWAM", // Rachel
+    edge: undefined, // resolved from language+gender by EdgeSpeechModel
+};
 // ─── Tool: audio_transcribe ───
 const AudioTranscribeSchema = Type.Object({
     path: Type.String({ description: "Path to the audio file to transcribe (mp3, wav, flac, ogg, m4a, webm)" }),
-    provider: Type.Optional(Type.Union([
-        Type.Literal("openai"),
-        Type.Literal("deepgram"),
-    ], { description: "STT provider (default: openai)" })),
-    model: Type.Optional(Type.String({ description: "Model name. OpenAI: 'whisper-1' (default). Deepgram: 'nova-3' (default)." })),
+    model: Type.Optional(Type.String({
+        description: "Override the agent's transcribe_model for this call. Format: '<provider>/<model>' " +
+            "(e.g. 'openai/whisper-1', 'deepgram/nova-3'). When omitted, uses the agent's configured transcribe_model.",
+    })),
     language: Type.Optional(Type.String({ description: "ISO 639-1 language code (e.g. 'en', 'it', 'es'). Helps accuracy." })),
-    prompt: Type.Optional(Type.String({ description: "Optional context/prompt to guide transcription (OpenAI only)" })),
+    prompt: Type.Optional(Type.String({ description: "Optional context/prompt to guide transcription (OpenAI Whisper only)" })),
 });
-function createTranscribeTool(cwd, sandbox, fs, vault) {
+function createTranscribeTool(cwd, sandbox, fs, configuredModel, vault) {
     return {
         name: "audio_transcribe",
         label: "Transcribe Audio",
         description: "Transcribe an audio file to text using speech-to-text AI. " +
             "Supports mp3, wav, flac, ogg, m4a, webm formats. Max file size: 25 MB. " +
-            "Providers: openai (Whisper, default), deepgram (Nova). " +
-            "Credentials resolved from: agent vault > OPENAI_API_KEY or DEEPGRAM_API_KEY env var.",
+            "Model is configured at agent level (transcribe_model) — pass `model` here only to override per-call. " +
+            "Default: openai/whisper-1. Supported providers: openai, deepgram.",
         parameters: AudioTranscribeSchema,
         async execute(_id, params, signal) {
             const filePath = resolve(cwd, params.path);
             assertPathAllowed(filePath, sandbox, "audio_transcribe");
-            const provider = params.provider ?? "openai";
             if (!fs.readFileBuffer) {
                 return {
                     content: [{ type: "text", text: "FileSystem implementation does not support readFileBuffer (required for binary reads)." }],
@@ -113,111 +86,61 @@ function createTranscribeTool(cwd, sandbox, fs, vault) {
                 };
             }
             try {
-                if (provider === "openai") {
-                    return await transcribeOpenAI(filePath, fileBuffer, params, vault, signal);
-                }
-                else {
-                    return await transcribeDeepgram(filePath, fileBuffer, params, vault, signal);
-                }
+                const parsed = resolveEffectiveModel(params.model, configuredModel, DEFAULT_TRANSCRIBE_MODEL);
+                return await transcribeWithSdk(filePath, fileBuffer, parsed, params, vault, signal);
             }
             catch (err) {
                 return {
-                    content: [{ type: "text", text: `Transcription error (${provider}): ${err.message}` }],
-                    details: { provider, error: err.message },
+                    content: [{ type: "text", text: `Transcription error: ${err.message}` }],
+                    details: { error: err.message },
                 };
             }
         },
     };
 }
-async function transcribeOpenAI(filePath, fileBuffer, params, vault, signal) {
-    const apiKey = vault?.getKey("openai", "key") ?? requireEnv("OPENAI_API_KEY");
-    const model = params.model ?? "whisper-1";
-    const fields = { model };
-    if (params.language)
-        fields.language = params.language;
-    if (params.prompt)
-        fields.prompt = params.prompt;
-    fields.response_format = "verbose_json";
-    const { body } = audioFormData(fileBuffer, filePath.split("/").pop(), fields);
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
-    if (signal)
-        signal.addEventListener("abort", () => controller.abort(), { once: true });
-    const response = await fetch("https://api.openai.com/v1/audio/transcriptions", {
-        method: "POST",
-        headers: { Authorization: `Bearer ${apiKey}` },
-        body,
-        signal: controller.signal,
-    });
-    clearTimeout(timer);
-    if (!response.ok) {
-        const errText = await response.text();
-        throw new Error(`OpenAI API ${response.status}: ${errText}`);
+async function transcribeWithSdk(_filePath, fileBuffer, parsed, params, vault, signal) {
+    const { experimental_transcribe } = await import("ai");
+    const apiKey = parsed.provider === "openai"
+        ? vault?.getKey("openai", "key") ?? requireEnv("OPENAI_API_KEY")
+        : parsed.provider === "deepgram"
+            ? vault?.getKey("deepgram", "key") ?? requireEnv("DEEPGRAM_API_KEY")
+            : (() => { throw new Error(`Unsupported transcribe provider: ${parsed.provider}`); })();
+    const provider = await resolveTranscribeProvider(parsed.provider, apiKey);
+    const providerOptions = {};
+    if (parsed.provider === "openai") {
+        const opts = {};
+        if (params.language)
+            opts.language = params.language;
+        if (params.prompt)
+            opts.prompt = params.prompt;
+        if (Object.keys(opts).length)
+            providerOptions.openai = opts;
     }
-    const data = await response.json();
-    const info = [
-        `Language: ${data.language ?? "unknown"}`,
-        `Duration: ${data.duration ? `${data.duration.toFixed(1)}s` : "unknown"}`,
-        `Model: ${model}`,
-    ].join(" | ");
-    return {
-        content: [{ type: "text", text: `${info}\n\n${data.text}` }],
-        details: {
-            provider: "openai",
-            model,
-            language: data.language,
-            duration: data.duration,
-            textLength: data.text.length,
-        },
-    };
-}
-async function transcribeDeepgram(filePath, fileBuffer, params, vault, signal) {
-    const apiKey = vault?.getKey("deepgram", "key") ?? requireEnv("DEEPGRAM_API_KEY");
-    const model = params.model ?? "nova-3";
-    const queryParams = new URLSearchParams({
-        model,
-        smart_format: "true",
-        punctuate: "true",
-    });
-    if (params.language)
-        queryParams.set("language", params.language);
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
-    if (signal)
-        signal.addEventListener("abort", () => controller.abort(), { once: true });
-    const ext = extname(filePath).toLowerCase();
-    const mime = mimeFromExt(ext);
-    const response = await fetch(`https://api.deepgram.com/v1/listen?${queryParams}`, {
-        method: "POST",
-        headers: {
-            Authorization: `Token ${apiKey}`,
-            "Content-Type": mime,
-        },
-        body: new Uint8Array(fileBuffer),
-        signal: controller.signal,
-    });
-    clearTimeout(timer);
-    if (!response.ok) {
-        const errText = await response.text();
-        throw new Error(`Deepgram API ${response.status}: ${errText}`);
+    else {
+        const opts = { smart_format: true, punctuate: true };
+        if (params.language)
+            opts.language = params.language;
+        providerOptions.deepgram = opts;
     }
-    const data = await response.json();
-    const transcript = data.results?.channels?.[0]?.alternatives?.[0]?.transcript ?? "";
-    const confidence = data.results?.channels?.[0]?.alternatives?.[0]?.confidence;
-    const duration = data.metadata?.duration;
+    const result = await experimental_transcribe({
+        model: provider.transcription(parsed.model),
+        audio: new Uint8Array(fileBuffer),
+        providerOptions: Object.keys(providerOptions).length ? providerOptions : undefined,
+        abortSignal: signal,
+    });
     const info = [
-        `Confidence: ${confidence ? `${(confidence * 100).toFixed(1)}%` : "unknown"}`,
-        `Duration: ${duration ? `${duration.toFixed(1)}s` : "unknown"}`,
-        `Model: ${model}`,
+        `Language: ${result.language ?? "unknown"}`,
+        `Duration: ${result.durationInSeconds ? `${result.durationInSeconds.toFixed(1)}s` : "unknown"}`,
+        `Model: ${parsed.provider}/${parsed.model}`,
     ].join(" | ");
     return {
-        content: [{ type: "text", text: `${info}\n\n${transcript}` }],
+        content: [{ type: "text", text: `${info}\n\n${result.text}` }],
         details: {
-            provider: "deepgram",
-            model,
-            confidence,
-            duration,
-            textLength: transcript.length,
+            provider: parsed.provider,
+            model: parsed.model,
+            language: result.language,
+            duration: result.durationInSeconds,
+            textLength: result.text.length,
         },
     };
 }
@@ -225,324 +148,118 @@ async function transcribeDeepgram(filePath, fileBuffer, params, vault, signal) {
 const AudioSpeakSchema = Type.Object({
     text: Type.String({ description: "Text to convert to speech" }),
     path: Type.String({ description: "Output file path (e.g. 'output.mp3'). Format inferred from extension." }),
-    provider: Type.Optional(Type.Union([
-        Type.Literal("openai"),
-        Type.Literal("deepgram"),
-        Type.Literal("elevenlabs"),
-        Type.Literal("edge"),
-    ], { description: "TTS provider. 'openai' (default), 'deepgram', 'elevenlabs', or 'edge' (free, local Microsoft Edge TTS — no API key needed). If the chosen provider fails, edge-tts is tried as automatic fallback." })),
-    model: Type.Optional(Type.String({ description: "Model name. OpenAI: 'tts-1' (default), 'tts-1-hd', 'gpt-4o-mini-tts'. Deepgram: 'aura-2-en' (default). ElevenLabs: 'eleven_multilingual_v2' (default)." })),
-    voice: Type.Optional(Type.String({ description: "Voice name/ID. OpenAI: alloy, echo, fable, onyx, nova, shimmer (default: alloy). ElevenLabs: voice ID. Edge: full voice name like 'it-IT-DiegoNeural' (auto-selected from language+gender if omitted)." })),
+    model: Type.Optional(Type.String({
+        description: "Override the agent's tts_model for this call. Format: '<provider>/<model>' " +
+            "(e.g. 'openai/tts-1', 'openai/tts-1-hd', 'openai/gpt-4o-mini-tts', 'deepgram/aura-2-asteria-en', " +
+            "'elevenlabs/eleven_multilingual_v2', 'edge/edge-tts'). When omitted, uses the agent's configured tts_model.",
+    })),
+    voice: Type.Optional(Type.String({ description: "Voice name/ID. OpenAI: alloy/echo/fable/onyx/nova/shimmer (default: alloy). ElevenLabs: voice ID (default: Rachel). Edge: full voice name like 'it-IT-DiegoNeural' (auto-selected from language+gender if omitted)." })),
     language: Type.Optional(Type.String({ description: "ISO 639-1 language code (e.g. 'it', 'en', 'es'). Used by edge provider to select the right voice. Also useful for other providers with multilingual models." })),
     gender: Type.Optional(Type.Union([
         Type.Literal("male"),
         Type.Literal("female"),
-    ], { description: "Voice gender preference. Used by edge provider to pick the right voice when no explicit voice is given. For other providers, choose the voice directly." })),
+    ], { description: "Voice gender preference. Used by the edge provider to pick the right voice when no explicit voice is given." })),
     speed: Type.Optional(Type.Number({ description: "Playback speed 0.25-4.0 (OpenAI only, default: 1.0)" })),
     instructions: Type.Optional(Type.String({ description: "Voice style instructions (OpenAI gpt-4o-mini-tts only, e.g. 'Speak in a cheerful tone')" })),
 });
-function createSpeakTool(cwd, sandbox, fs, shell, vault) {
+function audioFormat(filePath, providerName) {
+    const ext = extname(filePath).toLowerCase().replace(".", "");
+    if (providerName === "elevenlabs") {
+        const map = { mp3: "mp3_44100_128", wav: "pcm_44100", flac: "flac" };
+        return map[ext] ?? "mp3_44100_128";
+    }
+    return ext || "mp3";
+}
+function createSpeakTool(cwd, sandbox, fs, shell, configuredModel, vault) {
     return {
         name: "audio_speak",
         label: "Text to Speech",
         description: "Generate speech audio from text using text-to-speech AI. " +
-            "Output format is inferred from file extension (mp3, wav, flac, opus, aac, pcm). " +
-            "Providers: openai (default), deepgram (Aura), elevenlabs, edge (free, no API key — Microsoft Edge neural voices). " +
-            "If the chosen provider fails (quota, auth, billing), edge-tts is tried automatically as fallback. " +
-            "Use 'language' (ISO 639-1) and 'gender' params to help select the right voice, especially for edge provider. " +
-            "Credentials resolved from: agent vault > OPENAI_API_KEY, DEEPGRAM_API_KEY, or ELEVENLABS_API_KEY env var.",
+            "Output format inferred from file extension (mp3, wav, flac, opus, aac, pcm). " +
+            "Model is configured at agent level (tts_model) — pass `model` here only to override per-call. " +
+            "Default: openai/tts-1. Supported providers: openai, deepgram, elevenlabs, edge (free, local Microsoft Edge TTS — no API key needed).",
         parameters: AudioSpeakSchema,
         async execute(_id, params, signal) {
             const filePath = resolve(cwd, params.path);
             assertPathAllowed(filePath, sandbox, "audio_speak");
-            const provider = params.provider ?? "openai";
-            // Direct edge-tts request — no fallback needed
-            if (provider === "edge") {
-                if (!(await edgeTtsAvailable(shell))) {
-                    return {
-                        content: [{ type: "text", text: "Edge TTS not available in this environment. Use openai/deepgram/elevenlabs instead." }],
-                        details: { provider: "edge", error: "edge_tts_unavailable" },
-                    };
-                }
-                try {
-                    return await speakEdgeTts(filePath, params, fs, shell);
-                }
-                catch (err) {
-                    return {
-                        content: [{ type: "text", text: `TTS error (edge): ${err.message}` }],
-                        details: { provider: "edge", error: err.message },
-                    };
-                }
-            }
-            // Provider with edge-tts fallback
             try {
-                if (provider === "openai") {
-                    return await speakOpenAI(filePath, params, fs, vault, signal);
-                }
-                else if (provider === "deepgram") {
-                    return await speakDeepgram(filePath, params, fs, vault, signal);
-                }
-                else {
-                    return await speakElevenLabs(filePath, params, fs, vault, signal);
-                }
+                const parsed = resolveEffectiveModel(params.model, configuredModel, DEFAULT_TTS_MODEL);
+                return await speakWithSdk(filePath, parsed, params, fs, shell, vault, signal);
             }
             catch (err) {
-                // Automatic fallback to edge-tts if available
-                if (await edgeTtsAvailable(shell)) {
-                    try {
-                        const result = await speakEdgeTts(filePath, params, fs, shell);
-                        // Prepend fallback notice
-                        const notice = `[Fallback] ${provider} failed (${err.message}), used edge-tts instead.\n`;
-                        return {
-                            content: [{ type: "text", text: notice + result.content[0].text }],
-                            details: { ...result.details, fallbackFrom: provider, fallbackReason: err.message },
-                        };
-                    }
-                    catch (edgeErr) {
-                        return {
-                            content: [{ type: "text", text: `TTS error (${provider}): ${err.message}\nEdge-tts fallback also failed: ${edgeErr.message}` }],
-                            details: { provider, error: err.message, edgeError: edgeErr.message },
-                        };
-                    }
-                }
                 return {
-                    content: [{ type: "text", text: `TTS error (${provider}): ${err.message}` }],
-                    details: { provider, error: err.message },
+                    content: [{ type: "text", text: `TTS error: ${err.message}` }],
+                    details: { error: err.message },
                 };
             }
         },
     };
 }
-async function speakOpenAI(filePath, params, fs, vault, signal) {
-    const apiKey = vault?.getKey("openai", "key") ?? requireEnv("OPENAI_API_KEY");
-    const model = params.model ?? "tts-1";
-    const voice = params.voice ?? "alloy";
-    const ext = extname(filePath).toLowerCase().replace(".", "");
-    const formatMap = {
-        mp3: "mp3", wav: "wav", flac: "flac", opus: "opus", aac: "aac", pcm: "pcm",
-    };
-    const responseFormat = formatMap[ext] ?? "mp3";
-    const body = {
-        model,
-        input: params.text,
-        voice,
-        response_format: responseFormat,
-    };
-    if (params.speed !== undefined)
-        body.speed = params.speed;
-    if (params.instructions)
-        body.instructions = params.instructions;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
-    if (signal)
-        signal.addEventListener("abort", () => controller.abort(), { once: true });
-    const response = await fetch("https://api.openai.com/v1/audio/speech", {
-        method: "POST",
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify(body),
-        signal: controller.signal,
-    });
-    clearTimeout(timer);
-    if (!response.ok) {
-        const errText = await response.text();
-        throw new Error(`OpenAI TTS API ${response.status}: ${errText}`);
+async function speakWithSdk(filePath, parsed, params, fs, shell, vault, signal) {
+    const { experimental_generateSpeech } = await import("ai");
+    const providerName = parsed.provider;
+    const voice = params.voice ?? SPEAK_DEFAULT_VOICES[providerName];
+    // Cloud providers need an apiKey. The edge provider needs shell+fs.
+    let apiKey;
+    if (providerName === "openai") {
+        apiKey = vault?.getKey("openai", "key") ?? requireEnv("OPENAI_API_KEY");
     }
-    const buffer = Buffer.from(await response.arrayBuffer());
-    if (!fs.writeFileBuffer) {
-        throw new Error("FileSystem implementation does not support writeFileBuffer (required for binary writes).");
+    else if (providerName === "deepgram") {
+        apiKey = vault?.getKey("deepgram", "key") ?? requireEnv("DEEPGRAM_API_KEY");
     }
-    await fs.mkdir(dirname(filePath));
-    await fs.writeFileBuffer(filePath, new Uint8Array(buffer));
-    return {
-        content: [{ type: "text", text: `Speech audio saved: ${filePath} (${(buffer.byteLength / 1024).toFixed(1)} KB, ${responseFormat}, voice: ${voice}, model: ${model})` }],
-        details: {
-            provider: "openai",
-            model,
-            voice,
-            format: responseFormat,
-            path: filePath,
-            bytes: buffer.byteLength,
-            textLength: params.text.length,
-        },
-    };
-}
-async function speakDeepgram(filePath, params, fs, vault, signal) {
-    const apiKey = vault?.getKey("deepgram", "key") ?? requireEnv("DEEPGRAM_API_KEY");
-    const model = params.model ?? "aura-2-en";
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
-    if (signal)
-        signal.addEventListener("abort", () => controller.abort(), { once: true });
-    const response = await fetch(`https://api.deepgram.com/v1/speak?model=${encodeURIComponent(model)}`, {
-        method: "POST",
-        headers: {
-            Authorization: `Token ${apiKey}`,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify({ text: params.text }),
-        signal: controller.signal,
-    });
-    clearTimeout(timer);
-    if (!response.ok) {
-        const errText = await response.text();
-        throw new Error(`Deepgram TTS API ${response.status}: ${errText}`);
+    else if (providerName === "elevenlabs") {
+        apiKey = vault?.getKey("elevenlabs", "key") ?? requireEnv("ELEVENLABS_API_KEY");
     }
-    const buffer = Buffer.from(await response.arrayBuffer());
-    if (!fs.writeFileBuffer) {
-        throw new Error("FileSystem implementation does not support writeFileBuffer (required for binary writes).");
+    else if (providerName !== "edge") {
+        throw new Error(`Unsupported tts provider: ${providerName}`);
     }
-    await fs.mkdir(dirname(filePath));
-    await fs.writeFileBuffer(filePath, new Uint8Array(buffer));
-    return {
-        content: [{ type: "text", text: `Speech audio saved: ${filePath} (${(buffer.byteLength / 1024).toFixed(1)} KB, model: ${model})` }],
-        details: {
-            provider: "deepgram",
-            model,
-            format: "mp3",
-            path: filePath,
-            bytes: buffer.byteLength,
-            textLength: params.text.length,
-        },
-    };
-}
-async function speakElevenLabs(filePath, params, fs, vault, signal) {
-    const apiKey = vault?.getKey("elevenlabs", "key") ?? requireEnv("ELEVENLABS_API_KEY");
-    const model = params.model ?? "eleven_multilingual_v2";
-    // ElevenLabs default voice: "Rachel" (21m00Tcm4TlvDq8ikWAM)
-    const voiceId = params.voice ?? "21m00Tcm4TlvDq8ikWAM";
-    const ext = extname(filePath).toLowerCase().replace(".", "");
-    const formatMap = {
-        mp3: "mp3_44100_128", wav: "pcm_44100", flac: "flac",
-    };
-    const outputFormat = formatMap[ext] ?? "mp3_44100_128";
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
-    if (signal)
-        signal.addEventListener("abort", () => controller.abort(), { once: true });
-    const response = await fetch(`https://api.elevenlabs.io/v1/text-to-speech/${voiceId}?output_format=${outputFormat}`, {
-        method: "POST",
-        headers: {
-            "xi-api-key": apiKey,
-            "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-            text: params.text,
-            model_id: model,
-        }),
-        signal: controller.signal,
+    const provider = await resolveSpeakProvider(providerName, { apiKey, shell, fs });
+    // Provider-specific knobs flow through providerOptions.
+    const providerOptions = {};
+    if (providerName === "openai") {
+        const opts = {};
+        if (params.speed !== undefined)
+            opts.speed = params.speed;
+        if (params.instructions)
+            opts.instructions = params.instructions;
+        if (Object.keys(opts).length)
+            providerOptions.openai = opts;
+    }
+    if (providerName === "edge" && params.gender) {
+        providerOptions.edge = { gender: params.gender };
+    }
+    const outputFormat = audioFormat(filePath, providerName);
+    const result = await experimental_generateSpeech({
+        model: provider.speech(parsed.model),
+        text: params.text,
+        voice,
+        outputFormat,
+        language: params.language,
+        instructions: params.instructions,
+        speed: params.speed,
+        providerOptions: Object.keys(providerOptions).length ? providerOptions : undefined,
+        abortSignal: signal,
     });
-    clearTimeout(timer);
-    if (!response.ok) {
-        const errText = await response.text();
-        throw new Error(`ElevenLabs API ${response.status}: ${errText}`);
+    const bytes = result.audio.uint8Array;
+    if (!bytes || bytes.byteLength === 0) {
+        throw new Error("No audio bytes in SDK response");
     }
-    const buffer = Buffer.from(await response.arrayBuffer());
     if (!fs.writeFileBuffer) {
         throw new Error("FileSystem implementation does not support writeFileBuffer (required for binary writes).");
     }
     await fs.mkdir(dirname(filePath));
-    await fs.writeFileBuffer(filePath, new Uint8Array(buffer));
+    await fs.writeFileBuffer(filePath, bytes);
+    const voiceLabel = voice ?? "(model-bound)";
+    const summary = `Speech audio saved: ${filePath} (${(bytes.byteLength / 1024).toFixed(1)} KB, ${outputFormat}, voice: ${voiceLabel}, model: ${parsed.provider}/${parsed.model})`;
     return {
-        content: [{ type: "text", text: `Speech audio saved: ${filePath} (${(buffer.byteLength / 1024).toFixed(1)} KB, voice: ${voiceId}, model: ${model})` }],
+        content: [{ type: "text", text: summary }],
         details: {
-            provider: "elevenlabs",
-            model,
-            voiceId,
+            provider: providerName,
+            model: parsed.model,
+            voice: voiceLabel,
             format: outputFormat,
             path: filePath,
-            bytes: buffer.byteLength,
-            textLength: params.text.length,
-        },
-    };
-}
-// ─── Edge TTS (free, local CLI, automatic fallback) ───
-/**
- * Default Edge TTS voices per language+gender.
- * Format: `${lang}-${region}-${name}Neural`
- * Each entry: [female, male]. First match wins.
- */
-const EDGE_VOICES = {
-    "it": ["it-IT-ElsaNeural", "it-IT-DiegoNeural"],
-    "en": ["en-US-EmmaMultilingualNeural", "en-US-AndrewMultilingualNeural"],
-    "es": ["es-ES-ElviraNeural", "es-ES-AlvaroNeural"],
-    "fr": ["fr-FR-DeniseNeural", "fr-FR-HenriNeural"],
-    "de": ["de-DE-KatjaNeural", "de-DE-ConradNeural"],
-    "pt": ["pt-BR-FranciscaNeural", "pt-BR-AntonioNeural"],
-    "ja": ["ja-JP-NanamiNeural", "ja-JP-KeitaNeural"],
-    "zh": ["zh-CN-XiaoxiaoNeural", "zh-CN-YunxiNeural"],
-    "ko": ["ko-KR-SunHiNeural", "ko-KR-InJoonNeural"],
-    "ar": ["ar-SA-ZariyahNeural", "ar-SA-HamedNeural"],
-    "hi": ["hi-IN-SwaraNeural", "hi-IN-MadhurNeural"],
-    "ru": ["ru-RU-SvetlanaNeural", "ru-RU-DmitryNeural"],
-    "nl": ["nl-NL-ColetteNeural", "nl-NL-MaartenNeural"],
-    "pl": ["pl-PL-AgnieszkaNeural", "pl-PL-MarekNeural"],
-    "tr": ["tr-TR-EmelNeural", "tr-TR-AhmetNeural"],
-    "sv": ["sv-SE-SofieNeural", "sv-SE-MattiasNeural"],
-};
-/**
- * Resolve the best Edge TTS voice for a given language and gender hint.
- * Falls back to en-US if the language is unknown.
- */
-function resolveEdgeVoice(voice, language, gender) {
-    // If the agent passed an explicit voice name like "it-IT-DiegoNeural", use it directly
-    if (voice && voice.includes("-") && voice.endsWith("Neural"))
-        return voice;
-    const lang = (language ?? "en").toLowerCase().split("-")[0]; // "it-IT" → "it"
-    const pair = EDGE_VOICES[lang] ?? EDGE_VOICES["en"];
-    return gender === "male" ? pair[1] : pair[0]; // default female if no gender hint
-}
-/** Per-Shell cache of "is edge-tts on PATH" — checked once per shell. */
-const _edgeTtsAvailable = new WeakMap();
-/** Check if edge-tts CLI is available, routed through the Shell so the
- *  check runs in the same environment as the actual TTS call (sandbox
- *  in cloud, local Node in OSS). */
-function edgeTtsAvailable(shell) {
-    const existing = _edgeTtsAvailable.get(shell);
-    if (existing)
-        return existing;
-    const fresh = shell
-        .execute("edge-tts --version", { timeout: 5000 })
-        .then((r) => r.exitCode === 0)
-        .catch(() => false);
-    _edgeTtsAvailable.set(shell, fresh);
-    return fresh;
-}
-/** Quote a CLI argument for inclusion in a `shell.execute` command line. */
-function quoteArg(arg) {
-    return `'${arg.replace(/'/g, `'\\''`)}'`;
-}
-async function speakEdgeTts(filePath, params, fs, shell) {
-    if (!(await edgeTtsAvailable(shell))) {
-        throw new Error("edge-tts CLI is not installed. Install it with: pip install edge-tts");
-    }
-    const voice = resolveEdgeVoice(params.voice, params.language, params.gender);
-    await fs.mkdir(dirname(filePath));
-    const cmd = [
-        "edge-tts",
-        "--text", quoteArg(params.text),
-        "--voice", quoteArg(voice),
-        "--write-media", quoteArg(filePath),
-    ].join(" ");
-    const result = await shell.execute(cmd, { timeout: DEFAULT_TIMEOUT });
-    if (result.exitCode !== 0) {
-        throw new Error(`edge-tts failed: ${(result.stderr || result.stdout || "").trim() || `exit ${result.exitCode}`}`);
-    }
-    let bytes = 0;
-    try {
-        const stat = await fs.stat(filePath);
-        bytes = stat?.size ?? 0;
-    }
-    catch { /* ignore */ }
-    return {
-        content: [{ type: "text", text: `Speech audio saved: ${filePath} (${(bytes / 1024).toFixed(1)} KB, voice: ${voice}, provider: edge-tts)` }],
-        details: {
-            provider: "edge",
-            voice,
-            path: filePath,
-            bytes,
+            bytes: bytes.byteLength,
             textLength: params.text.length,
         },
     };
@@ -551,21 +268,22 @@ export const ALL_AUDIO_TOOL_NAMES = ["audio_transcribe", "audio_speak"];
 /**
  * Create audio tools for speech-to-text and text-to-speech.
  *
- * @param cwd - Working directory for resolving file paths
- * @param allowedPaths - Sandbox paths for file validation
- * @param allowedTools - Optional filter
- * @param vault - Resolved vault credentials for credential resolution
+ * The 6-arg positional signature is preserved for back-compat. Prefer
+ * the options-object form for new callers.
  */
 export function createAudioTools(cwd, allowedPaths, allowedTools, vault, fs, shell) {
-    const sandbox = resolveAllowedPaths(cwd, allowedPaths);
-    const _fs = fs ?? new NodeFileSystem();
-    const _shell = shell ?? new NodeShell();
+    const opts = typeof cwd === "string"
+        ? { cwd, allowedPaths, allowedTools, vault, fs, shell }
+        : cwd;
+    const sandbox = resolveAllowedPaths(opts.cwd, opts.allowedPaths);
+    const _fs = opts.fs ?? new NodeFileSystem();
+    const _shell = opts.shell ?? new NodeShell();
     const factories = {
-        audio_transcribe: () => createTranscribeTool(cwd, sandbox, _fs, vault),
-        audio_speak: () => createSpeakTool(cwd, sandbox, _fs, _shell, vault),
+        audio_transcribe: () => createTranscribeTool(opts.cwd, sandbox, _fs, opts.transcribeModel, opts.vault),
+        audio_speak: () => createSpeakTool(opts.cwd, sandbox, _fs, _shell, opts.ttsModel, opts.vault),
     };
-    const names = allowedTools
-        ? ALL_AUDIO_TOOL_NAMES.filter(n => allowedTools.some(a => a.toLowerCase() === n))
+    const names = opts.allowedTools
+        ? ALL_AUDIO_TOOL_NAMES.filter(n => opts.allowedTools.some(a => a.toLowerCase() === n))
         : ALL_AUDIO_TOOL_NAMES;
     return names.map(n => factories[n]());
 }