@stabgan/openrouter-mcp-multimodal 4.5.0 → 4.5.3

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

@@ -3,48 +3,10 @@ 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;
-    /**
-     * Optional reference images. Each entry is one of:
-     *   - a `data:image/...;base64,...` URL,
-     *   - an `http(s)://` URL (OpenRouter fetches it),
-     *   - a local file path (sandboxed to `OPENROUTER_INPUT_DIR` /
-     *     `OPENROUTER_OUTPUT_DIR` / cwd, read + base64-encoded by the server).
-     *
-     * When provided, the user message becomes multimodal: a text prompt
-     * plus one `image_url` block per reference, in array order. Enables
-     * character / style consistency and image-to-image refinement on
-     * chat-image models that accept image inputs (Gemini Nano Banana,
-     * `openai/gpt-5.4-image-2`).
-     */
     input_images?: string[];
-    /**
-     * Override the default `modalities: ["image","text"]` sent to
-     * OpenRouter. Most callers should leave this unset. Provide e.g.
-     * `["text"]` to suppress image output for inspection / captioning,
-     * or other shapes for future model variants.
-     */
     modalities?: string[];
 }
 export declare function handleGenerateImage(request: {
@@ -64,11 +26,16 @@ export declare function handleGenerateImage(request: {
         text?: undefined;
     })[];
     _meta: {
-        usage?: {
+        usage: {
             prompt_tokens: number;
             completion_tokens: number;
             total_tokens: number;
-        } | undefined;
+        };
+        server_version: string;
+        save_path: string;
+        mime: string;
+    } | {
+        usage?: undefined;
         server_version: string;
         save_path: string;
         mime: string;
@@ -80,21 +47,16 @@ export declare function handleGenerateImage(request: {
         data: string;
     }[];
     _meta: {
-        usage?: {
+        usage: {
             prompt_tokens: number;
             completion_tokens: number;
             total_tokens: number;
-        } | undefined;
+        };
+        server_version: string;
+        mime: string;
+    } | {
+        usage?: undefined;
         server_version: string;
         mime: string;
     };
 }>;
-/**
- * Resolve a caller-supplied input image into a URL the chat-completions
- * API accepts. Local file paths are sandboxed via
- * `resolveSafeInputPath` (`OPENROUTER_INPUT_DIR` /
- * `OPENROUTER_OUTPUT_DIR` / cwd) and inlined as base64 data URLs.
- */
-export declare function resolveInputImage(ref: string): Promise<string>;
-export declare function mimeFromExt(ext: string): string | null;
-export declare function buildUserContent(prompt: string, inputImages?: string[]): Promise<string | OpenAI.Chat.Completions.ChatCompletionContentPart[]>;

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

@@ -1,15 +1,12 @@
 import { promises as fs } from 'fs';
-import path from 'node:path';
-import { resolveSafeOutputPath, resolveSafeInputPath, UnsafeOutputPathError } from './path-safety.js';
+import { resolveSafeOutputPath, UnsafeOutputPathError } from './path-safety.js';
 import { parseBase64DataUrl } from './fetch-utils.js';
+import { buildUserContent } from './generate-image-input.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';
 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',
@@ -32,9 +29,6 @@ export async function handleGenerateImage(request, openai) {
     if (!prompt?.trim()) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
-    // Audit entry. Bypasses the normal log level so operators always see a
-    // record of cost-incurring operations. Prompt preview is hard-capped
-    // at 80 chars to avoid PII spillage in log aggregators.
     logger.audit('generate_image.start', {
         model: model || DEFAULT_MODEL,
         prompt_preview: prompt.slice(0, 80),
@@ -43,15 +37,12 @@ export async function handleGenerateImage(request, openai) {
         save_path: save_path ? 'provided' : 'none',
         input_images_count: input_images?.length ?? 0,
     });
-    // 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(', ')}.`);
+        return invalidEnumError('aspect_ratio', aspect_ratio, VALID_ASPECT_RATIOS);
     }
     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(', ')}.`);
+        return invalidEnumError('image_size', image_size, VALID_IMAGE_SIZES);
     }
-    // Fail-fast on unsafe paths BEFORE spending tokens.
     let safePathResolved = null;
     if (save_path) {
         try {
@@ -64,9 +55,6 @@ export async function handleGenerateImage(request, openai) {
             return toolErrorFrom(ErrorCode.INTERNAL, err);
         }
     }
-    // Build the user message. With no `input_images`, this is the original
-    // string content; with refs, it becomes a multimodal
-    // ChatCompletionContentPart[] (text preamble + one image_url per ref).
     let content;
     try {
         content = await buildUserContent(prompt, input_images);
@@ -77,14 +65,6 @@ export async function handleGenerateImage(request, openai) {
         }
         return toolErrorFrom(ErrorCode.INVALID_INPUT, err, 'input_images');
     }
-    // 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. Caller can
-    //     override via the `modalities` field.
-    //   - `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;
@@ -93,7 +73,7 @@ export async function handleGenerateImage(request, openai) {
     const body = {
         model: model || DEFAULT_MODEL,
         messages: [{ role: 'user', content }],
-        modalities: modalities && modalities.length ? modalities : ['image', 'text'],
+        modalities: modalities?.length ? modalities : ['image', 'text'],
     };
     if (Object.keys(imageConfig).length > 0)
         body.image_config = imageConfig;
@@ -101,10 +81,6 @@ export async function handleGenerateImage(request, openai) {
         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) {
@@ -116,8 +92,6 @@ export async function handleGenerateImage(request, openai) {
     }
     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 messageContent = message.content;
         const text = typeof messageContent === 'string' ? messageContent : JSON.stringify(messageContent);
         return toolError(ErrorCode.UPSTREAM_REFUSED, `Model returned no image. Text response: ${text.slice(0, 300)}`, {
@@ -127,113 +101,56 @@ export async function handleGenerateImage(request, openai) {
     }
     if (safePathResolved) {
         try {
-            await fs.writeFile(safePathResolved, Buffer.from(base64.data, 'base64'));
+            await fs.writeFile(safePathResolved, base64.data, { encoding: 'base64' });
         }
         catch (err) {
             return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
         }
-        const usage = completion.usage;
+    }
+    return buildImageSuccessResult(base64, completion.usage, safePathResolved ?? undefined);
+}
+function invalidEnumError(field, value, allowed) {
+    return toolError(ErrorCode.INVALID_INPUT, `${field} '${value}' is not supported. Valid values: ${[...allowed].join(', ')}.`);
+}
+function buildImageSuccessResult(base64, usage, savePath) {
+    const usageMeta = usage
+        ? {
+            usage: {
+                prompt_tokens: usage.prompt_tokens,
+                completion_tokens: usage.completion_tokens,
+                total_tokens: usage.total_tokens,
+            },
+        }
+        : {};
+    if (savePath) {
         return {
             content: [
-                { type: 'text', text: `Image saved to: ${safePathResolved}` },
+                { type: 'text', text: `Image saved to: ${savePath}` },
                 { type: 'image', mimeType: base64.mime, data: base64.data },
             ],
             _meta: {
                 server_version: SERVER_VERSION,
-                save_path: safePathResolved,
+                save_path: savePath,
                 mime: base64.mime,
-                ...(usage
-                    ? {
-                        usage: {
-                            prompt_tokens: usage.prompt_tokens,
-                            completion_tokens: usage.completion_tokens,
-                            total_tokens: usage.total_tokens,
-                        },
-                    }
-                    : {}),
+                ...usageMeta,
             },
         };
     }
-    const usage = completion.usage;
     return {
         content: [{ type: 'image', mimeType: base64.mime, data: base64.data }],
         _meta: {
             server_version: SERVER_VERSION,
             mime: base64.mime,
-            ...(usage
-                ? {
-                    usage: {
-                        prompt_tokens: usage.prompt_tokens,
-                        completion_tokens: usage.completion_tokens,
-                        total_tokens: usage.total_tokens,
-                    },
-                }
-                : {}),
+            ...usageMeta,
         },
     };
 }
-/**
- * Resolve a caller-supplied input image into a URL the chat-completions
- * API accepts. Local file paths are sandboxed via
- * `resolveSafeInputPath` (`OPENROUTER_INPUT_DIR` /
- * `OPENROUTER_OUTPUT_DIR` / cwd) and inlined as base64 data URLs.
- */
-export async function resolveInputImage(ref) {
-    const trimmed = ref.trim();
-    if (!trimmed)
-        throw new Error('empty input_images entry');
-    if (trimmed.startsWith('data:'))
-        return trimmed;
-    if (/^https?:\/\//i.test(trimmed))
-        return trimmed;
-    const abs = await resolveSafeInputPath(trimmed);
-    const buf = await fs.readFile(abs);
-    const mime = mimeFromExt(path.extname(abs)) || 'image/png';
-    return `data:${mime};base64,${buf.toString('base64')}`;
-}
-export function mimeFromExt(ext) {
-    const e = ext.toLowerCase().replace(/^\./, '');
-    switch (e) {
-        case 'png':
-            return 'image/png';
-        case 'jpg':
-        case 'jpeg':
-            return 'image/jpeg';
-        case 'webp':
-            return 'image/webp';
-        case 'gif':
-            return 'image/gif';
-        default:
-            return null;
-    }
-}
-export async function buildUserContent(prompt, inputImages) {
-    if (!inputImages?.length) {
-        return `Generate an image: ${prompt}`;
-    }
-    const parts = [
-        {
-            type: 'text',
-            text: `Generate an image based on this prompt, using the following reference image(s) ` +
-                `for visual consistency. Match the appearance, identity, and style of the references ` +
-                `closely; do not alter them.\n\nPrompt: ${prompt}`,
-        },
-    ];
-    for (const ref of inputImages) {
-        const url = await resolveInputImage(ref);
-        parts.push({
-            type: 'image_url',
-            image_url: { url, detail: 'high' },
-        });
-    }
-    return parts;
-}
 function extractBase64(message) {
     const images = message.images;
     if (Array.isArray(images) && images.length) {
         for (const img of images) {
             const imageUrl = img.image_url;
-            const result = parseDataUrl(imageUrl?.url || img.url);
+            const result = dataUrlToBase64(imageUrl?.url || img.url);
             if (result)
                 return result;
         }
@@ -243,7 +160,7 @@ function extractBase64(message) {
             const iu = part.image_url;
             const url = iu?.url || part.url;
             if (url) {
-                const r = parseDataUrl(url);
+                const r = dataUrlToBase64(url);
                 if (r)
                     return r;
             }
@@ -257,24 +174,20 @@ function extractBase64(message) {
         }
     }
     if (typeof message.content === 'string') {
-        // 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.
+        // Data URLs may carry MIME parameters (e.g. charset=binary) that break naive regexes.
         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);
+            const parsed = dataUrlToBase64(url);
             if (parsed)
                 return parsed;
         }
     }
     return null;
 }
-function parseDataUrl(url) {
+function dataUrlToBase64(url) {
     if (!url?.startsWith('data:'))
         return null;
     const parsed = parseBase64DataUrl(url);

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

@@ -88,34 +88,40 @@ function buildRequestBody(args, model) {
     return body;
 }
 async function attachFrameImages(args, body) {
-    const frameImages = [];
+    const frameTasks = [];
     if (args.first_frame_image) {
-        const img = await prepareImageInput(args.first_frame_image);
-        if (img) {
-            frameImages.push({
-                frame_type: 'first_frame',
-                image: { url: `data:${img.mime};base64,${img.data}` },
-            });
-        }
+        frameTasks.push(prepareImageInput(args.first_frame_image).then((img) => img
+            ? {
+                kind: 'frame',
+                entry: {
+                    frame_type: 'first_frame',
+                    image: { url: `data:${img.mime};base64,${img.data}` },
+                },
+            }
+            : null));
     }
     if (args.last_frame_image) {
-        const img = await prepareImageInput(args.last_frame_image);
-        if (img) {
-            frameImages.push({
-                frame_type: 'last_frame',
-                image: { url: `data:${img.mime};base64,${img.data}` },
-            });
-        }
+        frameTasks.push(prepareImageInput(args.last_frame_image).then((img) => img
+            ? {
+                kind: 'frame',
+                entry: {
+                    frame_type: 'last_frame',
+                    image: { url: `data:${img.mime};base64,${img.data}` },
+                },
+            }
+            : null));
     }
+    const frameResults = await Promise.all(frameTasks);
+    const frameImages = frameResults
+        .filter((r) => r !== null)
+        .map((r) => r.entry);
     if (frameImages.length)
         body.frame_images = frameImages;
     if (args.reference_images?.length) {
-        const refs = [];
-        for (const src of args.reference_images) {
-            const img = await prepareImageInput(src);
-            if (img)
-                refs.push({ image: { url: `data:${img.mime};base64,${img.data}` } });
-        }
+        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}` } }));
         if (refs.length)
             body.input_references = refs;
     }
@@ -234,9 +240,7 @@ export async function handleGenerateVideo(request, apiClient, progress) {
     if (!args.prompt || !args.prompt.trim()) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
-    const model = args.model ||
-        process.env.OPENROUTER_DEFAULT_VIDEO_GEN_MODEL ||
-        FALLBACK_MODEL;
+    const model = args.model || process.env.OPENROUTER_DEFAULT_VIDEO_GEN_MODEL || FALLBACK_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.

package/dist/tool-handlers/health-check.js

@@ -20,7 +20,10 @@ export async function handleHealthCheck(_request, apiClient, modelCache) {
         errorMessage = err instanceof Error ? err.message : String(err);
     }
     const modelsCached = modelCache.isValid() ? modelCache.size() : 0;
-    const ok = apiKeyValid && modelsCached > 0;
+    // `ok` means the API was reachable and the key was accepted. An empty
+    // catalog counts as success (the API just returned no models) — callers
+    // branch on `models_cached` if they care about the count.
+    const ok = apiKeyValid;
     return buildStructuredResult({
         ok,
         server_version: SERVER_VERSION,

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

@@ -3,6 +3,7 @@ export declare const isBlockedIPv4: typeof _isBlockedIPv4;
 export declare const assertUrlSafeForFetch: typeof _assertUrlSafeForFetch;
 export declare function getMaxImageDimension(): number;
 export declare function getImageJpegQuality(): number;
+export declare function mimeFromExtension(ext: string): string | null;
 export declare function getMimeType(filePath: string): string;
 export declare function fetchHttpImage(urlString: string): Promise<Buffer>;
 export declare function fetchImage(source: string): Promise<Buffer>;

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

@@ -1,6 +1,7 @@
 import path from 'path';
 import { promises as fs } from 'fs';
 import { readEnvInt, isBlockedIPv4 as _isBlockedIPv4, assertUrlSafeForFetch as _assertUrlSafeForFetch, fetchHttpResource, parseBase64DataUrl, } from './fetch-utils.js';
+import { resolveSafeInputPath } from './path-safety.js';
 // Re-export for backward compatibility (tests import from image-utils)
 export const isBlockedIPv4 = _isBlockedIPv4;
 export const assertUrlSafeForFetch = _assertUrlSafeForFetch;
@@ -39,22 +40,29 @@ async function loadSharp() {
             sharpFn = fn ?? mod;
         }
         catch {
-            console.error('sharp not available, images will be sent unprocessed');
+            // sharp is optional — images will be sent unprocessed (larger but functional)
+            const { logger } = await import('../logger.js');
+            logger.warn('sharp not available, images will be sent unprocessed');
         }
     }
     return sharpFn;
 }
+const IMAGE_EXT_MIME = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+    gif: 'image/gif',
+    bmp: 'image/bmp',
+};
+export function mimeFromExtension(ext) {
+    const normalized = ext.toLowerCase().replace(/^\./, '');
+    if (!normalized)
+        return null;
+    return IMAGE_EXT_MIME[normalized] ?? null;
+}
 export function getMimeType(filePath) {
-    const ext = path.extname(filePath).toLowerCase();
-    const map = {
-        '.png': 'image/png',
-        '.jpg': 'image/jpeg',
-        '.jpeg': 'image/jpeg',
-        '.webp': 'image/webp',
-        '.gif': 'image/gif',
-        '.bmp': 'image/bmp',
-    };
-    return map[ext] || 'image/jpeg';
+    return mimeFromExtension(path.extname(filePath)) ?? 'image/jpeg';
 }
 export async function fetchHttpImage(urlString) {
     const { buffer } = await fetchHttpResource(urlString, {
@@ -77,7 +85,8 @@ export async function fetchImage(source) {
     if (source.startsWith('http://') || source.startsWith('https://')) {
         return fetchHttpImage(source);
     }
-    return fs.readFile(source);
+    const safe = await resolveSafeInputPath(source);
+    return fs.readFile(safe);
 }
 /**
  * Sniff image MIME type from magic bytes. Used to label the output of a
@@ -134,13 +143,14 @@ export async function optimizeImage(buffer) {
     const maxDim = getMaxImageDimension();
     const quality = getImageJpegQuality();
     try {
-        const meta = await sharp(buffer).metadata();
-        let pipeline = sharp(buffer);
+        const pipeline = sharp(buffer);
+        const meta = await pipeline.metadata();
+        let resized = pipeline;
         if (meta.width && meta.height && Math.max(meta.width, meta.height) > maxDim) {
             const opts = meta.width > meta.height ? { width: maxDim } : { height: maxDim };
-            pipeline = pipeline.resize(opts);
+            resized = pipeline.resize(opts);
         }
-        const out = await pipeline.jpeg({ quality }).toBuffer();
+        const out = await resized.jpeg({ quality }).toBuffer();
         return { base64: out.toString('base64'), mime: 'image/jpeg' };
     }
     catch {

package/dist/tool-handlers/openrouter-errors.d.ts

@@ -14,5 +14,9 @@ import { type ToolErrorResult } from '../errors.js';
  *   2. Message heuristics for common OpenRouter strings (credits, ZDR,
  *      "model does not exist", content policy, etc.).
  *   3. Default to INTERNAL to avoid leaking raw shapes.
+ *
+ * When the error carries a `Retry-After` header (on 429 / 503) we populate
+ * `_meta.retry_after_seconds` so agents can back off intelligently. We
+ * also attach canonical `suggestions[]` for common cases.
  */
-export declare function classifyUpstreamError(err: unknown, _contextMessage?: string): ToolErrorResult;
+export declare function classifyUpstreamError(err: unknown, contextMessage?: string): ToolErrorResult;