@stabgan/openrouter-mcp-multimodal 4.5.3 → 4.6.0

package/dist/tool-handlers/generate-image-dedicated.js

@@ -0,0 +1,176 @@
+/**
+ * generate_image_dedicated — uses OpenRouter's dedicated POST /api/v1/images
+ * endpoint (launched June 2026) for image generation. Supports normalized
+ * resolution tiers, aspect ratios, quality levels, output formats, and
+ * input_references for image-to-image workflows.
+ *
+ * This is distinct from the original `generate_image` tool which uses chat
+ * completions with `modalities: ['image', 'text']`. New image models are
+ * added exclusively to this dedicated endpoint.
+ */
+import { promises as fs } from 'fs';
+import path from 'node:path';
+import { resolveSafeOutputPath, resolveSafeInputPath, UnsafeOutputPathError } from './path-safety.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { SERVER_VERSION } from '../version.js';
+import { logger } from '../logger.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildCacheHeaders } from './cache.js';
+const DEFAULT_MODEL = 'google/gemini-2.5-flash-image';
+const VALID_RESOLUTIONS = new Set(['512', '0.5K', '1K', '2K', '4K']);
+const VALID_QUALITIES = new Set(['auto', 'low', 'medium', 'high']);
+const VALID_OUTPUT_FORMATS = new Set(['png', 'jpeg', 'webp', 'svg']);
+/**
+ * Resolve an input image reference (local path, URL, or data URL) into the
+ * OpenRouter `input_references` shape: `{ type: "image_url", image_url: { url } }`.
+ */
+async function resolveReference(source) {
+    const trimmed = source.trim();
+    if (!trimmed)
+        throw new Error('Empty input_references entry');
+    // Data URLs and HTTP URLs pass through directly
+    if (trimmed.startsWith('data:') || /^https?:\/\//i.test(trimmed)) {
+        return { type: 'image_url', image_url: { url: trimmed } };
+    }
+    // Local file: sandbox, read, and convert to data URL
+    const abs = await resolveSafeInputPath(trimmed);
+    const buf = await fs.readFile(abs);
+    const ext = path.extname(abs).toLowerCase();
+    const mime = ext === '.png' ? 'image/png' :
+        ext === '.webp' ? 'image/webp' :
+            ext === '.gif' ? 'image/gif' :
+                ext === '.svg' ? 'image/svg+xml' :
+                    'image/jpeg';
+    const dataUrl = `data:${mime};base64,${buf.toString('base64')}`;
+    return { type: 'image_url', image_url: { url: dataUrl } };
+}
+export async function handleGenerateImageDedicated(request, apiClient) {
+    const args = request.params.arguments ?? {};
+    const { prompt, model, resolution, aspect_ratio, quality, output_format, n, input_references, save_path, provider, cache, cache_ttl, cache_clear, } = args;
+    if (!prompt?.trim()) {
+        return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
+    }
+    logger.audit('generate_image_dedicated.start', {
+        model: model || DEFAULT_MODEL,
+        prompt_preview: prompt.slice(0, 80),
+        resolution,
+        aspect_ratio,
+        quality,
+        output_format,
+        input_references_count: input_references?.length ?? 0,
+        save_path: save_path ? 'provided' : 'none',
+    });
+    // Validate enums
+    if (resolution && !VALID_RESOLUTIONS.has(resolution)) {
+        return toolError(ErrorCode.INVALID_INPUT, `resolution '${resolution}' is not supported. Valid: ${[...VALID_RESOLUTIONS].join(', ')}.`);
+    }
+    if (quality && !VALID_QUALITIES.has(quality)) {
+        return toolError(ErrorCode.INVALID_INPUT, `quality '${quality}' is not supported. Valid: ${[...VALID_QUALITIES].join(', ')}.`);
+    }
+    if (output_format && !VALID_OUTPUT_FORMATS.has(output_format)) {
+        return toolError(ErrorCode.INVALID_INPUT, `output_format '${output_format}' is not supported. Valid: ${[...VALID_OUTPUT_FORMATS].join(', ')}.`);
+    }
+    // Resolve save path early
+    let safeSavePath = null;
+    if (save_path) {
+        try {
+            safeSavePath = await resolveSafeOutputPath(save_path);
+        }
+        catch (err) {
+            if (err instanceof UnsafeOutputPathError)
+                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+            return toolErrorFrom(ErrorCode.INTERNAL, err);
+        }
+    }
+    // Build request body
+    const body = {
+        model: model || DEFAULT_MODEL,
+        prompt,
+    };
+    if (resolution)
+        body.resolution = resolution;
+    if (aspect_ratio)
+        body.aspect_ratio = aspect_ratio;
+    if (quality)
+        body.quality = quality;
+    if (output_format)
+        body.output_format = output_format;
+    if (typeof n === 'number' && n > 0)
+        body.n = n;
+    if (provider && typeof provider === 'object')
+        body.provider = provider;
+    // Resolve input references
+    if (input_references?.length) {
+        try {
+            const refs = await Promise.all(input_references.map(resolveReference));
+            body.input_references = refs;
+        }
+        catch (err) {
+            if (err instanceof UnsafeOutputPathError)
+                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+            return toolErrorFrom(ErrorCode.INVALID_INPUT, err, 'input_references');
+        }
+    }
+    // Build cache headers
+    const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
+    let response;
+    try {
+        response = await apiClient.generateImage(body, headers);
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'generate_image_dedicated');
+    }
+    const images = response.data ?? [];
+    if (!images.length || (!images[0]?.b64_json && !images[0]?.url)) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, 'Model returned no image data.', {
+            response_keys: Object.keys(response),
+        });
+    }
+    const firstImage = images[0];
+    const imageData = firstImage.b64_json;
+    const mimeType = output_format === 'png' ? 'image/png' :
+        output_format === 'webp' ? 'image/webp' :
+            output_format === 'svg' ? 'image/svg+xml' :
+                output_format === 'jpeg' ? 'image/jpeg' :
+                    'image/png'; // default
+    const baseMeta = {
+        server_version: SERVER_VERSION,
+        model: model || DEFAULT_MODEL,
+        images_count: images.length,
+    };
+    if (response.usage)
+        baseMeta.usage = response.usage;
+    if (firstImage.revised_prompt)
+        baseMeta.revised_prompt = firstImage.revised_prompt;
+    // Save to file if requested
+    if (safeSavePath && imageData) {
+        try {
+            await fs.writeFile(safeSavePath, imageData, { encoding: 'base64' });
+        }
+        catch (err) {
+            return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
+        }
+        baseMeta.save_path = safeSavePath;
+        return {
+            content: [
+                { type: 'text', text: `Image saved to: ${safeSavePath}` },
+                ...(imageData ? [{ type: 'image', mimeType, data: imageData }] : []),
+            ],
+            _meta: baseMeta,
+        };
+    }
+    // Return inline
+    if (imageData) {
+        return {
+            content: [{ type: 'image', mimeType, data: imageData }],
+            _meta: baseMeta,
+        };
+    }
+    // URL-only response (some models return URLs instead of base64)
+    return {
+        content: [
+            { type: 'text', text: `Image generated. URL: ${firstImage.url}` },
+        ],
+        _meta: { ...baseMeta, image_url: firstImage.url },
+    };
+}

package/dist/tool-handlers/generate-video.d.ts

@@ -34,7 +34,7 @@ export declare function handleGenerateVideo(request: {
     };
 }, apiClient: OpenRouterAPIClient, progress?: ProgressHook): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: "text";
+        type: string;
         text: string;
     }[];
     isError: false;
@@ -97,7 +97,7 @@ export declare function handleGenerateVideoFromImage(request: {
     };
 }, apiClient: OpenRouterAPIClient, progress?: ProgressHook): Promise<import("../errors.js").ToolErrorResult | {
     content: {
-        type: "text";
+        type: string;
         text: string;
     }[];
     isError: false;

package/dist/tool-handlers/generate-video.js

@@ -11,6 +11,34 @@ const DEFAULT_POLL_INTERVAL_MS = 15_000;
 const DEFAULT_MAX_WAIT_MS = 10 * 60_000;
 const MIN_POLL_INTERVAL_MS = 50; // just to avoid a 0ms busy-loop if a caller omits
 const INLINE_RETURN_CEILING_BYTES = 10 * 1024 * 1024;
+/** Models deprecated by OpenAI — removal date: 2026-09-24. */
+const SORA_DEPRECATED_MODELS = new Set([
+    'openai/sora-2',
+    'openai/sora-2-pro',
+    'openai/sora-2-2025-10-06',
+    'openai/sora-2-2025-12-08',
+    'openai/sora-2-pro-2025-10-06',
+]);
+const SORA_ALTERNATIVES = [
+    'google/veo-3.1 (recommended — fast, audio support)',
+    'google/veo-3.1-fast (budget-friendly)',
+    'bytedance/seedance-2.0 (high quality)',
+    'bytedance/seedance-2.0-fast (fast turnaround)',
+    'alibaba/wan-2.7 (good for artistic styles)',
+];
+/**
+ * Check if the model is a deprecated Sora model and return a warning string,
+ * or null if no deprecation applies.
+ */
+function checkSoraDeprecation(model) {
+    const normalized = model.toLowerCase().trim();
+    if (!SORA_DEPRECATED_MODELS.has(normalized) && !normalized.startsWith('openai/sora')) {
+        return null;
+    }
+    return (`⚠️ DEPRECATION WARNING: ${model} is deprecated by OpenAI and will be removed from the API on September 24, 2026. ` +
+        `Your request will still be attempted, but may fail. Recommended alternatives:\n` +
+        SORA_ALTERNATIVES.map((a) => `  • ${a}`).join('\n'));
+}
 function getMaxInlineBytes() {
     return readEnvInt('OPENROUTER_VIDEO_INLINE_MAX_BYTES', INLINE_RETURN_CEILING_BYTES, 4096);
 }
@@ -94,8 +122,9 @@ async function attachFrameImages(args, body) {
             ? {
                 kind: 'frame',
                 entry: {
+                    type: 'image_url',
+                    image_url: { url: `data:${img.mime};base64,${img.data}` },
                     frame_type: 'first_frame',
-                    image: { url: `data:${img.mime};base64,${img.data}` },
                 },
             }
             : null));
@@ -105,8 +134,9 @@ async function attachFrameImages(args, body) {
             ? {
                 kind: 'frame',
                 entry: {
+                    type: 'image_url',
+                    image_url: { url: `data:${img.mime};base64,${img.data}` },
                     frame_type: 'last_frame',
-                    image: { url: `data:${img.mime};base64,${img.data}` },
                 },
             }
             : null));
@@ -121,7 +151,10 @@ async function attachFrameImages(args, body) {
         const refResults = await Promise.all(args.reference_images.map((src) => prepareImageInput(src)));
         const refs = refResults
             .filter((img) => img !== null)
-            .map((img) => ({ image: { url: `data:${img.mime};base64,${img.data}` } }));
+            .map((img) => ({
+            type: 'image_url',
+            image_url: { url: `data:${img.mime};base64,${img.data}` },
+        }));
         if (refs.length)
             body.input_references = refs;
     }
@@ -241,6 +274,9 @@ export async function handleGenerateVideo(request, apiClient, progress) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
     const model = args.model || process.env.OPENROUTER_DEFAULT_VIDEO_GEN_MODEL || FALLBACK_MODEL;
+    // Sora deprecation warning — OpenAI is removing the Videos API and all
+    // Sora 2 model aliases on September 24, 2026. Warn and suggest alternatives.
+    const deprecationWarning = checkSoraDeprecation(model);
     // Audit entry — video is the most expensive tool we have. Always log
     // model, resolution, duration, and a safe prompt preview so unintended
     // spend can be traced.
@@ -301,13 +337,16 @@ export async function handleGenerateVideo(request, apiClient, progress) {
         });
     }
     if (outcome.kind === 'timeout') {
+        const timeoutContent = [];
+        if (deprecationWarning) {
+            timeoutContent.push({ type: 'text', text: deprecationWarning });
+        }
+        timeoutContent.push({
+            type: 'text',
+            text: `Video still generating after ${maxWaitMs}ms. Use get_video_status with video_id=${envelope.id} to resume.`,
+        });
         return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Video still generating after ${maxWaitMs}ms. Use get_video_status with video_id=${envelope.id} to resume.`,
-                },
-            ],
+            content: timeoutContent,
             isError: false,
             _meta: {
                 server_version: SERVER_VERSION,
@@ -320,6 +359,11 @@ export async function handleGenerateVideo(request, apiClient, progress) {
     }
     try {
         const { content, _meta } = await finalizeCompletedJob(apiClient, outcome.status, safeSavePath);
+        // Prepend deprecation warning if applicable
+        if (deprecationWarning) {
+            content.unshift({ type: 'text', text: deprecationWarning });
+            _meta.deprecated_model = true;
+        }
         return { content, _meta };
     }
     catch (err) {

package/dist/tool-handlers/path-safety.js

@@ -14,11 +14,31 @@
  */
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
+import os from 'node:os';
+/**
+ * Resolve the output root directory. On Windows, `process.cwd()` can be
+ * a system directory (e.g. `C:\Windows\System32`) when spawned by MCP
+ * clients without a working directory override. We detect that case and
+ * fall back to a writable temp directory to avoid EPERM errors.
+ */
 function getOutputRoot() {
     const override = process.env.OPENROUTER_OUTPUT_DIR;
     if (override && override.length > 0)
         return path.resolve(override);
-    return process.cwd();
+    const cwd = process.cwd();
+    // On Windows, avoid using system directories as the default output root.
+    // Common non-writable defaults when MCP clients spawn without a cwd:
+    //   C:\Windows\System32, C:\Windows, C:\Program Files\...
+    if (process.platform === 'win32') {
+        const cwdLower = cwd.toLowerCase().replace(/\\/g, '/');
+        if (cwdLower.startsWith('c:/windows') ||
+            cwdLower.startsWith('c:/program files') ||
+            cwdLower.startsWith('c:/program files (x86)')) {
+            const fallback = path.join(os.homedir(), 'openrouter-mcp-output');
+            return fallback;
+        }
+    }
+    return cwd;
 }
 function isUnsafeMode() {
     const v = process.env.OPENROUTER_ALLOW_UNSAFE_PATHS;
@@ -89,9 +109,7 @@ async function findExistingAncestor(dir) {
 /**
  * Root-resolution for caller-supplied INPUT paths. Prefers
  * `OPENROUTER_INPUT_DIR`, then `OPENROUTER_OUTPUT_DIR`, then `process.cwd()`.
- * This mirrors the semantics `generate_image`'s `input_images` originally
- * shipped with; exposing it here lets `generate_video`'s frame and
- * reference images use the same sandbox.
+ * On Windows, applies the same system-directory detection as getOutputRoot.
  */
 function getInputRoot() {
     const inputDir = process.env.OPENROUTER_INPUT_DIR;
@@ -100,7 +118,16 @@ function getInputRoot() {
     const outputDir = process.env.OPENROUTER_OUTPUT_DIR;
     if (outputDir && outputDir.length > 0)
         return path.resolve(outputDir);
-    return process.cwd();
+    const cwd = process.cwd();
+    if (process.platform === 'win32') {
+        const cwdLower = cwd.toLowerCase().replace(/\\/g, '/');
+        if (cwdLower.startsWith('c:/windows') ||
+            cwdLower.startsWith('c:/program files') ||
+            cwdLower.startsWith('c:/program files (x86)')) {
+            return path.join(os.homedir(), 'openrouter-mcp-output');
+        }
+    }
+    return cwd;
 }
 /**
  * Resolve and validate a caller-supplied INPUT path. Unlike

package/dist/tool-handlers/speech-to-text.d.ts

@@ -0,0 +1,20 @@
+import type { OpenRouterAPIClient } from '../openrouter-api.js';
+import { type CacheOptions } from './cache.js';
+export interface SpeechToTextRequest extends CacheOptions {
+    audio_path: string;
+    model?: string;
+    language?: string;
+    response_format?: string;
+    temperature?: number;
+}
+export declare function handleSpeechToText(request: {
+    params: {
+        arguments: SpeechToTextRequest;
+    };
+}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    _meta: Record<string, unknown>;
+}>;

package/dist/tool-handlers/speech-to-text.js

@@ -0,0 +1,140 @@
+/**
+ * speech_to_text — uses OpenRouter's dedicated POST /api/v1/audio/transcriptions
+ * endpoint (launched May 2026) for speech-to-text transcription. Faster and more
+ * cost-efficient than routing through chat completions for pure transcription.
+ *
+ * Supported models: OpenAI Whisper-1, GPT-4o Transcribe, GPT-4o Mini Transcribe,
+ * Mistral Voxtral Mini Transcribe.
+ */
+import { promises as fs } from 'fs';
+import path from 'node:path';
+import { resolveSafeInputPath, UnsafeOutputPathError } from './path-safety.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { SERVER_VERSION } from '../version.js';
+import { logger } from '../logger.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildCacheHeaders } from './cache.js';
+const DEFAULT_MODEL = 'openai/whisper-1';
+const VALID_RESPONSE_FORMATS = new Set(['json', 'text', 'srt', 'verbose_json', 'vtt']);
+/** Infer audio format from file extension. */
+function audioFormatFromExt(ext) {
+    const normalized = ext.toLowerCase().replace('.', '');
+    switch (normalized) {
+        case 'mp3': return 'mp3';
+        case 'mp4':
+        case 'm4a': return 'mp4';
+        case 'wav': return 'wav';
+        case 'flac': return 'flac';
+        case 'ogg':
+        case 'oga': return 'ogg';
+        case 'webm': return 'webm';
+        case 'opus': return 'opus';
+        default: return 'mp3';
+    }
+}
+/**
+ * Resolve audio input to base64 + format, supporting:
+ * - data: URLs (pass through)
+ * - http(s) URLs (fetch)
+ * - local file paths (sandboxed read)
+ */
+async function resolveAudioInput(audioPath) {
+    const trimmed = audioPath.trim();
+    if (!trimmed)
+        throw new Error('audio_path is empty');
+    // Data URL
+    if (trimmed.startsWith('data:')) {
+        const match = trimmed.match(/^data:audio\/([^;,]+)(?:;[^,]*)*;base64,(.+)$/);
+        if (!match)
+            throw new Error('Invalid audio data URL format');
+        return { data: match[2], format: match[1] };
+    }
+    // HTTP URL
+    if (/^https?:\/\//i.test(trimmed)) {
+        const { fetchHttpResource } = await import('./fetch-utils.js');
+        const { buffer, contentType } = await fetchHttpResource(trimmed, {
+            timeoutMs: 60_000,
+            maxBytes: 100 * 1024 * 1024,
+            maxRedirects: 8,
+        });
+        const format = contentType?.match(/audio\/(\w+)/)?.[1] || 'mp3';
+        return { data: buffer.toString('base64'), format };
+    }
+    // Local file
+    const abs = await resolveSafeInputPath(trimmed);
+    const buf = await fs.readFile(abs);
+    const ext = path.extname(abs);
+    const format = audioFormatFromExt(ext);
+    return { data: buf.toString('base64'), format };
+}
+export async function handleSpeechToText(request, apiClient) {
+    const args = request.params.arguments ?? {};
+    const { audio_path, model, language, response_format, temperature, cache, cache_ttl, cache_clear, } = args;
+    if (!audio_path?.trim()) {
+        return toolError(ErrorCode.INVALID_INPUT, 'audio_path is required.');
+    }
+    if (response_format && !VALID_RESPONSE_FORMATS.has(response_format)) {
+        return toolError(ErrorCode.INVALID_INPUT, `response_format '${response_format}' is not supported. Valid: ${[...VALID_RESPONSE_FORMATS].join(', ')}.`);
+    }
+    logger.audit('speech_to_text.start', {
+        model: model || DEFAULT_MODEL,
+        audio_path: audio_path.startsWith('data:') ? 'data_url' : audio_path.slice(0, 80),
+        language,
+        response_format,
+    });
+    // Resolve audio input
+    let audioInput;
+    try {
+        audioInput = await resolveAudioInput(audio_path);
+    }
+    catch (err) {
+        if (err instanceof UnsafeOutputPathError)
+            return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('Blocked host'))
+            return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+    }
+    // Build request body
+    const body = {
+        model: model || DEFAULT_MODEL,
+        input_audio: {
+            data: audioInput.data,
+            format: audioInput.format,
+        },
+    };
+    if (language)
+        body.language = language;
+    if (response_format)
+        body.response_format = response_format;
+    if (typeof temperature === 'number')
+        body.temperature = temperature;
+    const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
+    let response;
+    try {
+        response = await apiClient.transcribeAudio(body, headers);
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'speech_to_text');
+    }
+    const text = response.text;
+    if (!text) {
+        return toolError(ErrorCode.INTERNAL, 'Transcription returned no text.', {
+            response_keys: Object.keys(response),
+        });
+    }
+    const baseMeta = {
+        server_version: SERVER_VERSION,
+        model: model || DEFAULT_MODEL,
+    };
+    if (response.language)
+        baseMeta.language = response.language;
+    if (response.duration)
+        baseMeta.duration_seconds = response.duration;
+    if (response.usage)
+        baseMeta.usage = response.usage;
+    return {
+        content: [{ type: 'text', text }],
+        _meta: baseMeta,
+    };
+}

package/dist/tool-handlers/text-to-speech.d.ts

@@ -0,0 +1,29 @@
+import type { OpenRouterAPIClient } from '../openrouter-api.js';
+import { type CacheOptions } from './cache.js';
+export interface TextToSpeechRequest extends CacheOptions {
+    input: string;
+    model?: string;
+    voice?: string;
+    response_format?: string;
+    speed?: number;
+    instructions?: string;
+    save_path?: string;
+}
+export declare function handleTextToSpeech(request: {
+    params: {
+        arguments: TextToSpeechRequest;
+    };
+}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
+    content: ({
+        type: "text";
+        text: string;
+        mimeType?: undefined;
+        data?: undefined;
+    } | {
+        type: "audio";
+        mimeType: string;
+        data: string;
+        text?: undefined;
+    })[];
+    _meta: Record<string, unknown>;
+}>;

package/dist/tool-handlers/text-to-speech.js

@@ -0,0 +1,105 @@
+/**
+ * text_to_speech — uses OpenRouter's dedicated POST /api/v1/audio/speech
+ * endpoint (launched May 2026) for text-to-speech. Faster and more cost-efficient
+ * than routing through chat completions with audio modality.
+ *
+ * Supported providers: OpenAI (GPT-4o Mini TTS), Google (Gemini Flash TTS),
+ * Mistral (Voxtral Mini TTS).
+ */
+import { promises as fs } from 'fs';
+import { extname } from 'path';
+import { resolveSafeOutputPath, UnsafeOutputPathError } from './path-safety.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { SERVER_VERSION } from '../version.js';
+import { logger } from '../logger.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { buildCacheHeaders } from './cache.js';
+const DEFAULT_MODEL = 'openai/gpt-4o-mini-tts-2025-12-15';
+const DEFAULT_VOICE = 'alloy';
+const VALID_FORMATS = new Set(['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm']);
+export async function handleTextToSpeech(request, apiClient) {
+    const args = request.params.arguments ?? {};
+    const { input, model, voice, response_format, speed, instructions, save_path, cache, cache_ttl, cache_clear, } = args;
+    if (!input?.trim()) {
+        return toolError(ErrorCode.INVALID_INPUT, 'input text is required.');
+    }
+    if (response_format && !VALID_FORMATS.has(response_format)) {
+        return toolError(ErrorCode.INVALID_INPUT, `response_format '${response_format}' is not supported. Valid: ${[...VALID_FORMATS].join(', ')}.`);
+    }
+    logger.audit('text_to_speech.start', {
+        model: model || DEFAULT_MODEL,
+        voice: voice || DEFAULT_VOICE,
+        response_format: response_format || 'mp3',
+        input_preview: input.slice(0, 80),
+        save_path: save_path ? 'provided' : 'none',
+    });
+    // Resolve save path early
+    let safeSavePath = null;
+    if (save_path) {
+        try {
+            safeSavePath = await resolveSafeOutputPath(save_path);
+        }
+        catch (err) {
+            if (err instanceof UnsafeOutputPathError)
+                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+            return toolErrorFrom(ErrorCode.INTERNAL, err);
+        }
+    }
+    // Build request body
+    const body = {
+        model: model || DEFAULT_MODEL,
+        input,
+        voice: voice || DEFAULT_VOICE,
+    };
+    if (response_format)
+        body.response_format = response_format;
+    if (typeof speed === 'number' && speed > 0)
+        body.speed = speed;
+    if (instructions)
+        body.instructions = instructions;
+    const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
+    let result;
+    try {
+        result = await apiClient.generateSpeech(body, headers);
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'text_to_speech');
+    }
+    const { buffer, contentType } = result;
+    const mimeType = contentType.split(';')[0]?.trim() || 'audio/mpeg';
+    // Determine file extension from format
+    const ext = response_format || 'mp3';
+    const baseMeta = {
+        server_version: SERVER_VERSION,
+        model: model || DEFAULT_MODEL,
+        mime: mimeType,
+        size_bytes: buffer.length,
+        voice: voice || DEFAULT_VOICE,
+    };
+    if (safeSavePath) {
+        // Ensure extension matches
+        const currentExt = extname(safeSavePath).toLowerCase().slice(1);
+        const actualPath = currentExt === ext ? safeSavePath : `${safeSavePath}.${ext}`;
+        try {
+            await fs.writeFile(actualPath, buffer);
+        }
+        catch (err) {
+            return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
+        }
+        baseMeta.save_path = actualPath;
+        return {
+            content: [
+                { type: 'text', text: `Speech saved to: ${actualPath}` },
+                { type: 'audio', mimeType, data: buffer.toString('base64') },
+            ],
+            _meta: baseMeta,
+        };
+    }
+    return {
+        content: [
+            { type: 'text', text: `Speech generated (${buffer.length} bytes, ${mimeType}).` },
+            { type: 'audio', mimeType, data: buffer.toString('base64') },
+        ],
+        _meta: baseMeta,
+    };
+}