@stabgan/openrouter-mcp-multimodal 4.6.2 → 4.8.0

package/dist/tool-descriptions.js

@@ -55,8 +55,8 @@ export const TOOL_DESCRIPTIONS = {
             'You already know the model id (or rely on the server default)',
         ],
         notWhen: [
-            'Input is an image/audio/video file → use analyze_image / analyze_audio / analyze_video',
-            'You need to create images, audio, or video → use generate_* tools',
+            'Input is a single image/audio/video file → use analyze_image / analyze_audio / analyze_video (dedicated wrappers)',
+            'You need to create images, audio, or video → use generate_* / text_to_speech tools',
             'You only need to check if a model exists → use validate_model',
         ],
         goodExamples: [
@@ -136,14 +136,14 @@ export const TOOL_DESCRIPTIONS = {
             'The image is a local file under the input sandbox, a public https URL, or a data URL',
         ],
         notWhen: [
-            'You want to generate a new image → use generate_image',
+            'You want to generate a new image → use generate_image or generate_image_dedicated',
             'You need multi-file batch analysis in one call → not supported; call once per image',
-            'Pure text chat → use chat_completion with a vision-capable model instead (less ergonomic)',
+            'Multi-turn vision chat with several images → use chat_completion with a vision model (analyze_image is single-image only)',
         ],
         goodExamples: [
             '`{ "image_path": "diagram.png", "question": "List every label in this diagram." }`',
             '`{ "image_path": "https://example.com/photo.jpg", "question": "Describe the scene." }`',
-            '`{ "model": "google/gemini-2.5-flash", "image_path": "scan.jpg", "question": "Extract text" }`',
+            '`{ "image_path": "scan.jpg", "question": "Extract text", "model": "google/gemini-2.5-flash" }` (optional model override)',
         ],
         badExamples: [
             '`{ "url": "photo.jpg" }` → wrong key; use `image_path`',
@@ -166,9 +166,9 @@ export const TOOL_DESCRIPTIONS = {
             'Format is a common audio container the decoder recognizes',
         ],
         notWhen: [
-            'You want text-to-speech → use generate_audio',
+            'You want text-to-speech → use text_to_speech (dedicated, faster) or generate_audio (chat route, music/SFX)',
+            'You want pure transcription without Q&A → use speech_to_text',
             'Input is video → use analyze_video (or extract audio first)',
-            'Pure text chat → use chat_completion',
         ],
         goodExamples: [
             '`{ "audio_path": "meeting.wav", "question": "Transcribe verbatim." }`',
@@ -290,13 +290,15 @@ export const TOOL_DESCRIPTIONS = {
         worksWith: ['get_model_info', 'chat_completion'],
     }),
     generate_image: buildToolDescription({
-        summary: 'Generate an image from a text prompt. Optional `input_images` condition style/identity. ' +
-            'Default model: google/gemini-2.5-flash-image.',
+        summary: 'Generate an image via chat completions (modalities route). Optional `input_images` for style/identity. ' +
+            'Default model: google/gemini-2.5-flash-image. Use generate_image_dedicated for resolution/quality/format control or newer Image API models.',
         useWhen: [
-            'You need a new image from a text prompt',
-            'You have reference images for style or subject consistency',
+            'You need a new image from a text prompt via the chat-completions route',
+            'You have reference images for style or subject consistency (`input_images`)',
+            'Simple text-to-image without dedicated API knobs',
         ],
         notWhen: [
+            'You need resolution tiers, quality, output_format, or Image API-only models → generate_image_dedicated',
             'You want to analyze an existing image → analyze_image',
             'You want video → generate_video or generate_video_from_image',
             'Prompt is empty or only whitespace',
@@ -329,6 +331,7 @@ export const TOOL_DESCRIPTIONS = {
             'You need image-to-image with `input_references`',
         ],
         notWhen: [
+            'Simple text-to-image without format/resolution control → generate_image (fewer params)',
             'You want to analyze an existing image → analyze_image',
             'You want video → generate_video or generate_video_from_image',
             'Prompt is empty or only whitespace',
@@ -352,12 +355,17 @@ export const TOOL_DESCRIPTIONS = {
         worksWith: ['analyze_image', 'generate_video_from_image'],
     }),
     generate_audio: buildToolDescription({
-        summary: 'Generate speech or music from a text prompt. Output format is auto-detected; file extension auto-corrected on save.',
+        summary: 'Generate speech or music via chat completions (modalities route). Formats: wav, mp3, flac, opus, pcm16. ' +
+            'Default model: openai/gpt-audio, voice alloy. Use text_to_speech for dedicated TTS with speed/instructions.',
         useWhen: [
-            'You need TTS or audio generation from text',
-            'Optional save_path is inside the output sandbox',
+            'You need music, sound effects, or expressive speech via the chat route',
+            'You want pcm16/wav output from the gpt-audio family',
+        ],
+        notWhen: [
+            'You want fast dedicated TTS with speed/instructions → text_to_speech',
+            'You want to transcribe existing audio → speech_to_text or analyze_audio',
+            'Prompt is empty',
         ],
-        notWhen: ['You want to transcribe existing audio → analyze_audio', 'Prompt is empty'],
         goodExamples: [
             '`{ "prompt": "Say hello world in a calm voice." }`',
             '`{ "prompt": "Upbeat jingle", "save_path": "out/jingle.mp3" }`',

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

@@ -4,7 +4,7 @@ import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { extractCompletionText, detectReasoningCutoff, buildCompletionMeta, } from './completion-utils.js';
-import { buildCacheHeaders, extractCacheMeta } from './cache.js';
+import { buildCacheHeaders, extractCacheMeta, validateCacheOptions, } from './cache.js';
 import { awaitCompletionWithHeaders } from './openai-withresponse.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash';
 export async function handleAnalyzeAudio(request, openai, defaultModel) {
@@ -13,6 +13,9 @@ export async function handleAnalyzeAudio(request, openai, defaultModel) {
     if (!audio_path) {
         return toolError(ErrorCode.INVALID_INPUT, 'audio_path is required.');
     }
+    const cacheError = validateCacheOptions({ cache, cache_ttl, cache_clear });
+    if (cacheError)
+        return cacheError;
     let audioData;
     try {
         audioData = await prepareAudioData(audio_path);

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

@@ -4,7 +4,7 @@ import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { extractCompletionText, detectReasoningCutoff, buildCompletionMeta, } from './completion-utils.js';
-import { buildCacheHeaders, extractCacheMeta } from './cache.js';
+import { buildCacheHeaders, extractCacheMeta, validateCacheOptions, } from './cache.js';
 import { awaitCompletionWithHeaders } from './openai-withresponse.js';
 const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
 export async function handleAnalyzeImage(request, openai, defaultModel) {
@@ -13,6 +13,9 @@ export async function handleAnalyzeImage(request, openai, defaultModel) {
     if (!image_path) {
         return toolError(ErrorCode.INVALID_INPUT, 'image_path is required.');
     }
+    const cacheError = validateCacheOptions({ cache, cache_ttl, cache_clear });
+    if (cacheError)
+        return cacheError;
     let imageUrl;
     try {
         imageUrl = await prepareImageUrl(image_path);
@@ -22,12 +25,14 @@ export async function handleAnalyzeImage(request, openai, defaultModel) {
             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);
+        const detail = `image_path "${image_path}": ${msg}`;
+        if (msg.includes('Blocked host')) {
+            return toolError(ErrorCode.UPSTREAM_REFUSED, detail);
+        }
         if (msg.toLowerCase().includes('too large')) {
-            return toolErrorFrom(ErrorCode.RESOURCE_TOO_LARGE, err);
+            return toolError(ErrorCode.RESOURCE_TOO_LARGE, detail);
         }
-        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+        return toolError(ErrorCode.INVALID_INPUT, detail);
     }
     const imageBlock = {
         type: 'image_url',

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

@@ -5,7 +5,7 @@ import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { extractCompletionText, detectReasoningCutoff, buildCompletionMeta, } from './completion-utils.js';
-import { buildCacheHeaders, extractCacheMeta } from './cache.js';
+import { buildCacheHeaders, extractCacheMeta, validateCacheOptions, } from './cache.js';
 import { awaitCompletionWithHeaders } from './openai-withresponse.js';
 const FALLBACK_DEFAULT_MODEL = 'google/gemini-2.5-flash';
 export async function handleAnalyzeVideo(request, openai, defaultModel) {
@@ -14,6 +14,9 @@ export async function handleAnalyzeVideo(request, openai, defaultModel) {
     if (!video_path) {
         return toolError(ErrorCode.INVALID_INPUT, 'video_path is required.');
     }
+    const cacheError = validateCacheOptions({ cache, cache_ttl, cache_clear });
+    if (cacheError)
+        return cacheError;
     const pickedModel = model || process.env.OPENROUTER_DEFAULT_VIDEO_MODEL || defaultModel || FALLBACK_DEFAULT_MODEL;
     let videoData;
     try {
@@ -24,16 +27,17 @@ export async function handleAnalyzeVideo(request, openai, defaultModel) {
             return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
         }
         const msg = err instanceof Error ? err.message : String(err);
+        const detail = `video_path "${video_path}": ${msg}`;
         if (msg.includes('Blocked host')) {
-            return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+            return toolError(ErrorCode.UPSTREAM_REFUSED, detail);
         }
         if (msg.includes('too large')) {
-            return toolErrorFrom(ErrorCode.RESOURCE_TOO_LARGE, err);
+            return toolError(ErrorCode.RESOURCE_TOO_LARGE, detail);
         }
         if (msg.includes('Unsupported') || msg.includes('not a video')) {
-            return toolErrorFrom(ErrorCode.UNSUPPORTED_FORMAT, err);
+            return toolError(ErrorCode.UNSUPPORTED_FORMAT, detail);
         }
-        return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
+        return toolError(ErrorCode.INVALID_INPUT, detail);
     }
     const videoBlock = {
         type: 'video_url',

package/dist/tool-handlers/async-chat.d.ts

@@ -18,6 +18,10 @@ export interface AsyncJob {
     error?: string;
     error_code?: ErrorCode;
 }
+/** Test-only reset for module-level job state. */
+export declare function resetAsyncJobStateForTests(): void;
+/** Exported for tests — produces ids accepted by `isValidJobId`. */
+export declare function generateJobId(): string;
 /** Load a persisted job from disk (exported for tests). */
 export declare function loadJobFromDisk(jobId: string): Promise<AsyncJob | null>;
 export declare function handleStartChatCompletion(request: {
@@ -41,6 +45,19 @@ export declare function handleGetChatCompletionStatus(request: {
         arguments: GetChatCompletionStatusRequest;
     };
 }): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    _meta: {
+        result_truncated?: boolean | undefined;
+        server_version: string;
+        job_id: string;
+        status: "completed";
+        model: string;
+        created_at: string;
+    };
+} | {
     content: {
         type: "text";
         text: string;

package/dist/tool-handlers/async-chat.js

@@ -1,18 +1,54 @@
 /** Async chat completions — in-memory jobs, optionally persisted under OPENROUTER_OUTPUT_DIR/openrouter-jobs/. */
+import { randomBytes } from 'node:crypto';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { ErrorCode, toolError } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
-import { extractCompletionText, buildCompletionMeta } from './completion-utils.js';
+import { extractCompletionText, buildCompletionMeta, capResultText } from './completion-utils.js';
+import { resolveSafeJobStatusPath, isValidJobId } from './path-safety.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
-import { DEFAULT_CHAT_MODEL, buildChatCompletionBody, buildChatCompletionRequestOpts, asOpenAIChatBody, readIncludeReasoningDefault, } from './chat-request.js';
+import { validateCacheOptions } from './cache.js';
+import { DEFAULT_CHAT_MODEL, buildChatCompletionBody, buildChatCompletionRequestOpts, asOpenAIChatBody, readIncludeReasoningDefault, validateChatMessages, validateMaxTokens, } from './chat-request.js';
 const jobs = new Map();
 let jobCounter = 0;
-function generateJobId() {
+const DEFAULT_ASYNC_JOBS_MEMORY_MAX = 200;
+function readAsyncJobsMemoryMax() {
+    const raw = process.env.OPENROUTER_ASYNC_JOBS_MEMORY_MAX;
+    if (raw === undefined || raw === '')
+        return DEFAULT_ASYNC_JOBS_MEMORY_MAX;
+    if (raw === '0')
+        return 0;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_ASYNC_JOBS_MEMORY_MAX;
+}
+function evictTerminalJobsIfNeeded() {
+    const max = readAsyncJobsMemoryMax();
+    if (max <= 0 || jobs.size < max)
+        return;
+    const terminal = [...jobs.entries()]
+        .filter(([, job]) => job.status === 'completed' || job.status === 'failed')
+        .sort((a, b) => a[1].createdAt.localeCompare(b[1].createdAt));
+    while (jobs.size > max && terminal.length > 0) {
+        const [id] = terminal.shift();
+        jobs.delete(id);
+    }
+}
+function rememberJob(job) {
+    evictTerminalJobsIfNeeded();
+    jobs.set(job.id, job);
+}
+/** Test-only reset for module-level job state. */
+export function resetAsyncJobStateForTests() {
+    jobs.clear();
+    jobCounter = 0;
+}
+/** Exported for tests — produces ids accepted by `isValidJobId`. */
+export function generateJobId() {
     jobCounter += 1;
     const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 14);
-    return `chat_${ts}_${String(jobCounter).padStart(3, '0')}`;
+    const entropy = randomBytes(4).toString('hex');
+    return `chat_${ts}_${String(jobCounter).padStart(3, '0')}_${entropy}`;
 }
 function getJobsDir() {
     const outputDir = process.env.OPENROUTER_OUTPUT_DIR;
@@ -44,8 +80,11 @@ export async function loadJobFromDisk(jobId) {
     const dir = getJobsDir();
     if (!dir)
         return null;
+    const statusPath = await resolveSafeJobStatusPath(dir, jobId);
+    if (!statusPath)
+        return null;
     try {
-        const raw = await fs.readFile(path.join(dir, jobId, 'status.json'), 'utf8');
+        const raw = await fs.readFile(statusPath, 'utf8');
         return JSON.parse(raw);
     }
     catch {
@@ -58,7 +97,7 @@ async function resolveJob(jobId) {
         return inMemory;
     const fromDisk = await loadJobFromDisk(jobId);
     if (fromDisk) {
-        jobs.set(jobId, fromDisk);
+        rememberJob(fromDisk);
         return fromDisk;
     }
     return undefined;
@@ -66,9 +105,15 @@ async function resolveJob(jobId) {
 export async function handleStartChatCompletion(request, openai, defaultModel) {
     const args = request.params.arguments ?? { messages: [] };
     const { messages, model, temperature, max_tokens, provider, include_reasoning, online, web_max_results, cache, cache_ttl, cache_clear, } = args;
-    if (!messages?.length) {
-        return toolError(ErrorCode.INVALID_INPUT, 'Messages array cannot be empty.');
-    }
+    const messagesError = validateChatMessages(messages);
+    if (messagesError)
+        return messagesError;
+    const cacheError = validateCacheOptions({ cache, cache_ttl, cache_clear });
+    if (cacheError)
+        return cacheError;
+    const maxTokensError = validateMaxTokens(max_tokens);
+    if (maxTokensError)
+        return maxTokensError;
     const effectiveModel = model || defaultModel || DEFAULT_CHAT_MODEL;
     const jobId = generateJobId();
     const job = {
@@ -77,7 +122,7 @@ export async function handleStartChatCompletion(request, openai, defaultModel) {
         createdAt: new Date().toISOString(),
         model: effectiveModel,
     };
-    jobs.set(jobId, job);
+    rememberJob(job);
     logger.audit('async_chat.start', {
         job_id: jobId,
         model: effectiveModel,
@@ -95,6 +140,16 @@ export async function handleStartChatCompletion(request, openai, defaultModel) {
         cache,
         cache_ttl,
         cache_clear,
+    }).catch((err) => {
+        logger.error('async_chat.unhandled', {
+            job_id: job.id,
+            err: err instanceof Error ? err.message : String(err),
+        });
+        if (job.status === 'running') {
+            job.status = 'failed';
+            job.error = 'Unexpected error during background completion.';
+            job.error_code = ErrorCode.INTERNAL;
+        }
     });
     return {
         content: [
@@ -112,35 +167,56 @@ export async function handleStartChatCompletion(request, openai, defaultModel) {
     };
 }
 async function runCompletionInBackground(job, openai, opts) {
-    const wantsReasoning = opts.include_reasoning ?? readIncludeReasoningDefault();
-    const body = buildChatCompletionBody(opts);
-    const requestOpts = buildChatCompletionRequestOpts(opts);
     try {
-        const completion = (await openai.chat.completions.create(asOpenAIChatBody(body), requestOpts));
-        const extracted = extractCompletionText(completion);
-        if (!extracted.text) {
+        const cacheError = validateCacheOptions(opts);
+        if (cacheError) {
             job.status = 'failed';
-            job.error = 'Model returned no textual content.';
+            job.error = cacheError.content[0]?.text ?? 'Invalid cache options.';
+            job.error_code = cacheError._meta.code;
+            await persistJob(job);
+            evictTerminalJobsIfNeeded();
+            return;
         }
-        else {
-            job.status = 'completed';
-            job.result = {
-                text: extracted.text,
-                meta: buildCompletionMeta(extracted, {
-                    includeReasoning: wantsReasoning,
-                    extra: { server_version: SERVER_VERSION },
-                }),
-            };
+        const wantsReasoning = opts.include_reasoning ?? readIncludeReasoningDefault();
+        const body = buildChatCompletionBody(opts);
+        const requestOpts = buildChatCompletionRequestOpts(opts);
+        try {
+            const completion = (await openai.chat.completions.create(asOpenAIChatBody(body), requestOpts));
+            const extracted = extractCompletionText(completion);
+            if (!extracted.text) {
+                job.status = 'failed';
+                job.error = 'Model returned no textual content.';
+            }
+            else {
+                job.status = 'completed';
+                job.result = {
+                    text: extracted.text,
+                    meta: buildCompletionMeta(extracted, {
+                        includeReasoning: wantsReasoning,
+                        extra: { server_version: SERVER_VERSION },
+                    }),
+                };
+            }
+        }
+        catch (err) {
+            job.status = 'failed';
+            const classified = classifyUpstreamError(err);
+            job.error = classified.content[0]?.text ?? 'Job failed.';
+            job.error_code = classified._meta.code;
+            logger.warn('async_chat.failed', { job_id: job.id, error: job.error, code: job.error_code });
         }
     }
     catch (err) {
         job.status = 'failed';
-        const classified = classifyUpstreamError(err);
-        job.error = classified.content[0]?.text ?? 'Job failed.';
-        job.error_code = classified._meta.code;
-        logger.warn('async_chat.failed', { job_id: job.id, error: job.error, code: job.error_code });
+        job.error = 'Unexpected error during background completion.';
+        job.error_code = ErrorCode.INTERNAL;
+        logger.error('async_chat.background_error', {
+            job_id: job.id,
+            err: err instanceof Error ? err.message : String(err),
+        });
     }
     await persistJob(job);
+    evictTerminalJobsIfNeeded();
 }
 export async function handleGetChatCompletionStatus(request) {
     const args = request.params.arguments ?? {};
@@ -148,6 +224,9 @@ export async function handleGetChatCompletionStatus(request) {
     if (!jobId) {
         return toolError(ErrorCode.INVALID_INPUT, 'job_id is required.');
     }
+    if (!isValidJobId(jobId)) {
+        return toolError(ErrorCode.INVALID_INPUT, `Invalid job_id "${jobId}". Must start with chat_ and must not contain path separators.`);
+    }
     const job = await resolveJob(jobId);
     if (!job) {
         const hint = getJobsDir()
@@ -156,14 +235,16 @@ export async function handleGetChatCompletionStatus(request) {
         return toolError(ErrorCode.INVALID_INPUT, `No job found with id "${jobId}".${hint}`);
     }
     if (job.status === 'completed' && job.result) {
+        const capped = capResultText(job.result.text);
         return {
-            content: [{ type: 'text', text: job.result.text }],
+            content: [{ type: 'text', text: capped.text }],
             _meta: {
                 server_version: SERVER_VERSION,
                 job_id: jobId,
                 status: 'completed',
                 model: job.model,
                 created_at: job.createdAt,
+                ...(capped.truncated ? { result_truncated: true } : {}),
                 ...job.result.meta,
             },
         };

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

@@ -1,16 +1,31 @@
 export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
-/** File-extension formats (matchable by .ext) */
+/** Shared ceiling for speech_to_text local, HTTP, and data-URL inputs. */
+export declare function getMaxAudioInputBytes(): number;
 declare const FILE_AUDIO_FORMATS: readonly ["wav", "mp3", "aiff", "aac", "ogg", "flac", "m4a"];
 export declare const SUPPORTED_AUDIO_FORMATS: readonly ["wav", "mp3", "aiff", "aac", "ogg", "flac", "m4a", "pcm16", "pcm24"];
 export type AudioFormat = (typeof SUPPORTED_AUDIO_FORMATS)[number];
 type FileAudioFormat = (typeof FILE_AUDIO_FORMATS)[number];
-/** Get audio format from file extension. Returns undefined for non-audio or API-only formats. */
+export declare const STT_FILE_EXTENSIONS: readonly ["mp3", "mp4", "m4a", "wav", "flac", "ogg", "oga", "webm", "opus"];
+export type SttFileExtension = (typeof STT_FILE_EXTENSIONS)[number];
+/**
+ * Detect audio container format from magic bytes. MP3 detection is strict:
+ * ID3 tags or frame sync with valid MPEG header fields.
+ */
+export declare function detectAudioFormat(data: Buffer): {
+    ext: string;
+    mimeType: string;
+};
 export declare function getAudioFormat(filePath: string): FileAudioFormat | undefined;
-/** Get MIME type for an audio format. */
 export declare function getAudioMimeType(format: AudioFormat): string;
 export interface AudioData {
     data: string;
     format: AudioFormat;
 }
-/** Prepare audio from data URL, HTTP URL, or sandboxed local file. */
 export declare function prepareAudioData(source: string): Promise<AudioData>;
+/** Map a speech_to_text file extension to the upstream format slug. */
+export declare function sttFormatFromExtension(ext: string): string;
+/** Resolve speech_to_text audio from data URL, HTTP URL, or sandboxed local file. */
+export declare function resolveSpeechToTextAudio(audioPath: string): Promise<{
+    data: string;
+    format: string;
+}>;