@stabgan/openrouter-mcp-multimodal 2.0.0 → 3.1.0

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

@@ -1,14 +1,17 @@
 import { promises as fs } from 'fs';
-import { dirname, extname } from 'path';
+import { extname } from 'path';
+import { resolveSafeOutputPath, UnsafeOutputPathError } from './path-safety.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
 const DEFAULT_MODEL = 'openai/gpt-audio';
 const DEFAULT_VOICE = 'alloy';
 const DEFAULT_FORMAT = 'pcm16';
 const VALID_FORMATS = ['wav', 'mp3', 'flac', 'opus', 'pcm16'];
-const PCM_SAMPLE_RATE = 24000;
+const DEFAULT_PCM_SAMPLE_RATE = 24000;
 const PCM_BITS_PER_SAMPLE = 16;
 const PCM_NUM_CHANNELS = 1;
-/** Create a 44-byte WAV header for raw PCM16 data. */
-export function createWavHeader(dataLength, sampleRate = PCM_SAMPLE_RATE) {
+/** Create a 44-byte WAV header for raw PCM16 data at `sampleRate` Hz. */
+export function createWavHeader(dataLength, sampleRate = DEFAULT_PCM_SAMPLE_RATE) {
     const header = Buffer.alloc(44);
     const byteRate = sampleRate * PCM_NUM_CHANNELS * (PCM_BITS_PER_SAMPLE / 8);
     const blockAlign = PCM_NUM_CHANNELS * (PCM_BITS_PER_SAMPLE / 8);
@@ -28,20 +31,31 @@ export function createWavHeader(dataLength, sampleRate = PCM_SAMPLE_RATE) {
     return header;
 }
 /**
- * Detect audio container format from magic bytes.
- * Uses subarray (not deprecated slice). Tighter MP3 frame sync validation.
+ * Detect audio container format from magic bytes. Uses `Buffer.subarray()`
+ * (not deprecated `slice()`). MP3 detection is intentionally strict:
+ * - Accept ID3v2 tags (`'ID3'`) as unambiguous MP3.
+ * - Accept raw frame sync only when every MPEG header field falls in a
+ *   non-reserved range: version != 0b01, layer != 0b00, bitrate != 0b1111,
+ *   sample rate index != 0b11. This removes the false positives that a
+ *   sync-word-only check produces on random binary.
  */
 export function detectAudioFormat(data) {
-    if (data.length >= 3) {
-        if (data[0] === 0x49 && data[1] === 0x44 && data[2] === 0x33) {
+    if (data.length >= 3 && data[0] === 0x49 && data[1] === 0x44 && data[2] === 0x33) {
+        return { ext: 'mp3', mimeType: 'audio/mpeg' };
+    }
+    if (data.length >= 4 && data[0] === 0xff && (data[1] & 0xe0) === 0xe0) {
+        const b1 = data[1];
+        const b2 = data[2];
+        const versionBits = (b1 >> 3) & 0x03; // 01 = reserved
+        const layerBits = (b1 >> 1) & 0x03; // 00 = reserved
+        const bitrateIndex = (b2 >> 4) & 0x0f; // 1111 = bad
+        const sampleRateIndex = (b2 >> 2) & 0x03; // 11 = reserved
+        if (versionBits !== 0x01 &&
+            layerBits !== 0x00 &&
+            bitrateIndex !== 0x0f &&
+            sampleRateIndex !== 0x03) {
             return { ext: 'mp3', mimeType: 'audio/mpeg' };
         }
-        if (data[0] === 0xff && (data[1] & 0xe0) === 0xe0) {
-            const versionBits = (data[1] >> 3) & 0x03;
-            if (versionBits !== 0x01) {
-                return { ext: 'mp3', mimeType: 'audio/mpeg' };
-            }
-        }
     }
     if (data.length >= 12) {
         const riff = data.subarray(0, 4).toString('ascii');
@@ -59,8 +73,8 @@ export function detectAudioFormat(data) {
     }
     return { ext: 'pcm', mimeType: 'audio/pcm' };
 }
-export function wrapPcmInWav(pcmData) {
-    return Buffer.concat([createWavHeader(pcmData.length), pcmData]);
+export function wrapPcmInWav(pcmData, sampleRate = DEFAULT_PCM_SAMPLE_RATE) {
+    return Buffer.concat([createWavHeader(pcmData.length, sampleRate), pcmData]);
 }
 /** Strip existing extension (if any) and append a new one. */
 export function replaceExtension(filePath, newExt) {
@@ -69,39 +83,62 @@ export function replaceExtension(filePath, newExt) {
     return `${base}.${newExt}`;
 }
 export async function handleGenerateAudio(request, openai) {
-    const { prompt, model, voice, format, save_path } = request.params.arguments;
+    const { prompt, model, voice, format, save_path } = request.params.arguments ?? {
+        prompt: '',
+    };
     if (!prompt?.trim()) {
-        return { content: [{ type: 'text', text: 'Prompt is required.' }], isError: true };
+        return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
+    }
+    // Fail-fast on unsafe paths BEFORE spending tokens.
+    let safeBase = null;
+    if (save_path) {
+        try {
+            safeBase = await resolveSafeOutputPath(save_path);
+        }
+        catch (e) {
+            if (e instanceof UnsafeOutputPathError)
+                return toolErrorFrom(ErrorCode.UNSAFE_PATH, e);
+            return toolErrorFrom(ErrorCode.INTERNAL, e);
+        }
     }
     const selectedFormat = VALID_FORMATS.includes(format ?? '')
         ? format
         : DEFAULT_FORMAT;
     const selectedVoice = voice?.trim() || DEFAULT_VOICE;
+    let stream;
     try {
-        const stream = await openai.chat.completions.create({
+        stream = (await openai.chat.completions.create({
             model: model || DEFAULT_MODEL,
             messages: [{ role: 'user', content: prompt }],
             modalities: ['text', 'audio'],
             audio: { voice: selectedVoice, format: selectedFormat },
             stream: true,
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        });
+        }));
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'generate_audio');
+    }
+    try {
         const audioChunks = [];
         const transcriptChunks = [];
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         for await (const chunk of stream) {
-            const delta = chunk.choices?.[0]?.delta;
-            if (delta?.audio) {
-                if (delta.audio.data)
-                    audioChunks.push(delta.audio.data);
-                if (delta.audio.transcript)
-                    transcriptChunks.push(delta.audio.transcript);
+            const delta = chunk.choices?.[0]
+                ?.delta;
+            if (delta && typeof delta === 'object' && delta.audio) {
+                const a = delta.audio;
+                if (typeof a.data === 'string')
+                    audioChunks.push(a.data);
+                if (typeof a.transcript === 'string')
+                    transcriptChunks.push(a.transcript);
             }
         }
         const fullAudioBase64 = audioChunks.join('');
         const transcript = transcriptChunks.join('');
         if (!fullAudioBase64) {
-            return { content: [{ type: 'text', text: transcript || 'No audio generated.' }] };
+            return toolError(ErrorCode.INTERNAL, transcript
+                ? `No audio returned (model emitted transcript only): ${transcript.slice(0, 300)}`
+                : 'No audio returned.', { reason: 'no_audio_in_stream' });
         }
         let audioBuffer = Buffer.from(fullAudioBase64, 'base64');
         const detected = detectAudioFormat(audioBuffer);
@@ -112,13 +149,11 @@ export async function handleGenerateAudio(request, openai) {
             detected.mimeType = 'audio/wav';
         }
         const returnBase64 = audioBuffer.toString('base64');
-        if (save_path) {
-            const dir = dirname(save_path);
-            await fs.mkdir(dir, { recursive: true });
-            const fileExt = extname(save_path).toLowerCase().slice(1);
-            const actualSavePath = fileExt === detected.ext ? save_path : replaceExtension(save_path, detected.ext);
+        if (safeBase) {
+            const fileExt = extname(safeBase).toLowerCase().slice(1);
+            const actualSavePath = fileExt === detected.ext ? safeBase : replaceExtension(safeBase, detected.ext);
             await fs.writeFile(actualSavePath, audioBuffer);
-            const formatNote = actualSavePath !== save_path
+            const formatNote = actualSavePath !== safeBase
                 ? ` (detected ${detected.ext.toUpperCase()}, saved as ${actualSavePath})`
                 : '';
             const result = transcript
@@ -129,6 +164,11 @@ export async function handleGenerateAudio(request, openai) {
                     { type: 'text', text: result },
                     { type: 'audio', mimeType: detected.mimeType, data: returnBase64 },
                 ],
+                _meta: {
+                    save_path: actualSavePath,
+                    mime: detected.mimeType,
+                    size_bytes: audioBuffer.length,
+                },
             };
         }
         return {
@@ -136,19 +176,10 @@ export async function handleGenerateAudio(request, openai) {
                 { type: 'text', text: transcript || 'Audio generated successfully.' },
                 { type: 'audio', mimeType: detected.mimeType, data: returnBase64 },
             ],
+            _meta: { mime: detected.mimeType, size_bytes: audioBuffer.length },
         };
     }
-    catch (error) {
-        let msg;
-        if (error instanceof Error) {
-            msg = error.message;
-            const oaiErr = error;
-            if (oaiErr.error?.message)
-                msg = `${msg} - ${oaiErr.error.message}`;
-        }
-        else {
-            msg = String(error);
-        }
-        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    catch (err) {
+        return classifyUpstreamError(err, 'generate_audio (stream)');
     }
 }

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

@@ -3,28 +3,66 @@ export interface GenerateImageToolRequest {
     prompt: string;
     model?: string;
     save_path?: string;
+    /**
+     * Output aspect ratio. Passed through as `image_config.aspect_ratio`.
+     * Supported by OpenRouter image models (e.g. `1:1`, `16:9`, `9:16`,
+     * `4:3`, `3:4`, `21:9`). Model-dependent — unsupported values fall back
+     * to the model's default. See
+     * https://openrouter.ai/docs/guides/overview/multimodal/image-generation
+     */
+    aspect_ratio?: string;
+    /**
+     * Output image resolution bucket. Passed through as
+     * `image_config.image_size`. Typical values: `0.5K`, `1K` (default),
+     * `2K`, `4K`. Model-dependent.
+     */
+    image_size?: string;
+    /**
+     * Upper bound on the completion budget. Without this OpenRouter
+     * reserves the model's full context window (~29k for Gemini
+     * image models), which can trigger a 402 on low-credit accounts even
+     * though the actual generation uses far fewer tokens. 4096 is plenty
+     * for the image payload + any caption.
+     */
+    max_tokens?: number;
 }
 export declare function handleGenerateImage(request: {
     params: {
         arguments: GenerateImageToolRequest;
     };
-}, openai: OpenAI): Promise<{
-    content: {
-        type: string;
-        text: string;
-    }[];
-    isError: boolean;
-} | {
+}, openai: OpenAI): Promise<import("../errors.js").ToolErrorResult | {
     content: ({
-        type: string;
+        type: "text";
         text: string;
         mimeType?: undefined;
         data?: undefined;
     } | {
-        type: string;
+        type: "image";
         mimeType: string;
         data: string;
         text?: undefined;
     })[];
-    isError?: undefined;
+    _meta: {
+        usage?: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        } | undefined;
+        save_path: string;
+        mime: string;
+    };
+} | {
+    content: {
+        type: "image";
+        mimeType: string;
+        data: string;
+    }[];
+    _meta: {
+        usage?: {
+            prompt_tokens: number;
+            completion_tokens: number;
+            total_tokens: number;
+        } | undefined;
+        mime: string;
+    };
 }>;

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

@@ -1,43 +1,145 @@
 import { promises as fs } from 'fs';
-import { dirname } from 'path';
+import { resolveSafeOutputPath, UnsafeOutputPathError } from './path-safety.js';
+import { parseBase64DataUrl } from './fetch-utils.js';
+import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { classifyUpstreamError } from './openrouter-errors.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash-image';
+// OpenRouter-documented aspect ratios (standard + extended). Extended are
+// only honored by models that support them (e.g. gemini-3.1-flash-image),
+// others fall back to the model's default.
+const VALID_ASPECT_RATIOS = new Set([
+    '1:1',
+    '2:3',
+    '3:2',
+    '3:4',
+    '4:3',
+    '4:5',
+    '5:4',
+    '9:16',
+    '16:9',
+    '21:9',
+    '1:4',
+    '4:1',
+    '1:8',
+    '8:1',
+]);
+const VALID_IMAGE_SIZES = new Set(['0.5K', '1K', '2K', '4K']);
 export async function handleGenerateImage(request, openai) {
-    const { prompt, model, save_path } = request.params.arguments;
+    const { prompt, model, save_path, aspect_ratio, image_size, max_tokens } = request.params.arguments ?? { prompt: '' };
     if (!prompt?.trim()) {
-        return { content: [{ type: 'text', text: 'Prompt is required.' }], isError: true };
+        return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
-    try {
-        const completion = await openai.chat.completions.create({
-            model: model || DEFAULT_MODEL,
-            messages: [{ role: 'user', content: `Generate an image: ${prompt}` }],
-        });
-        const message = completion.choices[0]?.message;
-        if (!message) {
-            return { content: [{ type: 'text', text: 'No response from model.' }], isError: true };
+    // Validate optional shape fields early so callers get a clear error
+    // instead of a cryptic upstream 400.
+    if (aspect_ratio !== undefined && !VALID_ASPECT_RATIOS.has(aspect_ratio)) {
+        return toolError(ErrorCode.INVALID_INPUT, `aspect_ratio '${aspect_ratio}' is not supported. Valid values: ${[...VALID_ASPECT_RATIOS].join(', ')}.`);
+    }
+    if (image_size !== undefined && !VALID_IMAGE_SIZES.has(image_size)) {
+        return toolError(ErrorCode.INVALID_INPUT, `image_size '${image_size}' is not supported. Valid values: ${[...VALID_IMAGE_SIZES].join(', ')}.`);
+    }
+    // Fail-fast on unsafe paths BEFORE spending tokens.
+    let safePathResolved = null;
+    if (save_path) {
+        try {
+            safePathResolved = await resolveSafeOutputPath(save_path);
         }
-        const base64 = extractBase64(message);
-        if (base64) {
-            if (save_path) {
-                const dir = dirname(save_path);
-                await fs.mkdir(dir, { recursive: true });
-                await fs.writeFile(save_path, Buffer.from(base64.data, 'base64'));
-                return {
-                    content: [
-                        { type: 'text', text: `Image saved to: ${save_path}` },
-                        { type: 'image', mimeType: base64.mime, data: base64.data },
-                    ],
-                };
+        catch (err) {
+            if (err instanceof UnsafeOutputPathError) {
+                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
             }
-            return { content: [{ type: 'image', mimeType: base64.mime, data: base64.data }] };
+            return toolErrorFrom(ErrorCode.INTERNAL, err);
         }
+    }
+    // Assemble the request body. OpenRouter's image-generation guide requires
+    //   - `modalities: ["image", "text"]` so multimodal models (like Gemini)
+    //     know to emit an image, not just text;
+    //   - `image_config.{aspect_ratio, image_size}` for shape control.
+    // The OpenAI SDK doesn't type these fields, but passes unknown members
+    // through to the server, so we attach them via a typed cast.
+    const imageConfig = {};
+    if (aspect_ratio)
+        imageConfig.aspect_ratio = aspect_ratio;
+    if (image_size)
+        imageConfig.image_size = image_size;
+    const body = {
+        model: model || DEFAULT_MODEL,
+        messages: [{ role: 'user', content: `Generate an image: ${prompt}` }],
+        modalities: ['image', 'text'],
+    };
+    if (Object.keys(imageConfig).length > 0)
+        body.image_config = imageConfig;
+    if (typeof max_tokens === 'number' && max_tokens > 0)
+        body.max_tokens = max_tokens;
+    let completion;
+    try {
+        // OpenRouter-specific `image_config` isn't in the OpenAI SDK's typings,
+        // but the SDK passes unknown fields straight through to the server.
+        // We never pass `stream: true`, so the response is always
+        // ChatCompletion.
+        completion = (await openai.chat.completions.create(body));
+    }
+    catch (err) {
+        return classifyUpstreamError(err, 'generate_image');
+    }
+    const message = completion.choices[0]?.message;
+    if (!message) {
+        return toolError(ErrorCode.INTERNAL, 'No response from model.');
+    }
+    const base64 = extractBase64(message);
+    if (!base64) {
+        // Model talked but did not emit an image. Surface this as a distinct
+        // condition so callers don't treat chatter as a successful image.
         const content = message.content;
         const text = typeof content === 'string' ? content : JSON.stringify(content);
-        return { content: [{ type: 'text', text }] };
+        return toolError(ErrorCode.UPSTREAM_REFUSED, `Model returned no image. Text response: ${text.slice(0, 300)}`, {
+            reason: 'no_image_in_response',
+            finish_reason: completion.choices[0]?.finish_reason,
+        });
     }
-    catch (error) {
-        const msg = error instanceof Error ? error.message : String(error);
-        return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    if (safePathResolved) {
+        try {
+            await fs.writeFile(safePathResolved, Buffer.from(base64.data, 'base64'));
+        }
+        catch (err) {
+            return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
+        }
+        const usage = completion.usage;
+        return {
+            content: [
+                { type: 'text', text: `Image saved to: ${safePathResolved}` },
+                { type: 'image', mimeType: base64.mime, data: base64.data },
+            ],
+            _meta: {
+                save_path: safePathResolved,
+                mime: base64.mime,
+                ...(usage
+                    ? {
+                        usage: {
+                            prompt_tokens: usage.prompt_tokens,
+                            completion_tokens: usage.completion_tokens,
+                            total_tokens: usage.total_tokens,
+                        },
+                    }
+                    : {}),
+            },
+        };
     }
+    const usage = completion.usage;
+    return {
+        content: [{ type: 'image', mimeType: base64.mime, data: base64.data }],
+        _meta: {
+            mime: base64.mime,
+            ...(usage
+                ? {
+                    usage: {
+                        prompt_tokens: usage.prompt_tokens,
+                        completion_tokens: usage.completion_tokens,
+                        total_tokens: usage.total_tokens,
+                    },
+                }
+                : {}),
+        },
+    };
 }
 function extractBase64(message) {
     const images = message.images;
@@ -68,15 +170,28 @@ function extractBase64(message) {
         }
     }
     if (typeof message.content === 'string') {
-        const match = message.content.match(/data:image\/([^;]+);base64,([A-Za-z0-9+/=]+)/);
-        if (match)
-            return { data: match[2], mime: `image/${match[1]}` };
+        // Scan the string for an embedded data URL. We deliberately don't use
+        // a single regex here because data URLs may carry MIME parameters
+        // (e.g. `data:image/png;charset=binary;base64,...`) which trips the
+        // naive `data:([^;]+);base64,(.+)` form.
+        const start = message.content.indexOf('data:image/');
+        if (start >= 0) {
+            // Find the end of the data URL: a whitespace or closing quote/paren.
+            const tail = message.content.slice(start);
+            const end = tail.search(/[\s)"']/);
+            const url = end === -1 ? tail : tail.slice(0, end);
+            const parsed = parseDataUrl(url);
+            if (parsed)
+                return parsed;
+        }
     }
     return null;
 }
 function parseDataUrl(url) {
     if (!url?.startsWith('data:'))
         return null;
-    const match = url.match(/^data:([^;]+);base64,(.+)$/);
-    return match ? { data: match[2], mime: match[1] } : null;
+    const parsed = parseBase64DataUrl(url);
+    if (!parsed)
+        return null;
+    return { data: parsed.base64, mime: parsed.mediaType };
 }

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

@@ -0,0 +1,78 @@
+import type { OpenRouterAPIClient, VideoJobStatus } from '../openrouter-api.js';
+export interface GenerateVideoToolRequest {
+    prompt: string;
+    model?: string;
+    resolution?: string;
+    aspect_ratio?: string;
+    duration?: number;
+    seed?: number;
+    first_frame_image?: string;
+    last_frame_image?: string;
+    reference_images?: string[];
+    provider?: Record<string, unknown>;
+    save_path?: string;
+    max_wait_ms?: number;
+    poll_interval_ms?: number;
+}
+export interface GetVideoStatusToolRequest {
+    video_id: string;
+    save_path?: string;
+    polling_url?: string;
+}
+type ProgressHook = (update: {
+    status: string;
+    progress?: number;
+    attempt: number;
+    video_id: string;
+}) => void | Promise<void>;
+declare function buildRequestBody(args: GenerateVideoToolRequest, model: string): Record<string, unknown>;
+declare function extractJobError(status: VideoJobStatus): string;
+declare function stripAndReplaceExt(p: string, newExt: string): string;
+export declare function handleGenerateVideo(request: {
+    params: {
+        arguments: GenerateVideoToolRequest;
+    };
+}, apiClient: OpenRouterAPIClient, progress?: ProgressHook): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: false;
+    _meta: {
+        code: "JOB_STILL_RUNNING";
+        video_id: string;
+        polling_url: string;
+        last_status: string | undefined;
+    };
+} | {
+    content: Record<string, unknown>[];
+    _meta: Record<string, unknown>;
+    isError?: undefined;
+}>;
+export declare function handleGetVideoStatus(request: {
+    params: {
+        arguments: GetVideoStatusToolRequest;
+    };
+}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
+    content: Record<string, unknown>[];
+    _meta: Record<string, unknown>;
+    isError?: undefined;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: false;
+    _meta: {
+        code: "JOB_STILL_RUNNING";
+        video_id: string;
+        last_status: string;
+        progress: number | undefined;
+    };
+}>;
+export declare const _internals: {
+    buildRequestBody: typeof buildRequestBody;
+    stripAndReplaceExt: typeof stripAndReplaceExt;
+    extractJobError: typeof extractJobError;
+};
+export {};