@stabgan/openrouter-mcp-multimodal 4.0.1 → 4.5.0

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

@@ -1,8 +1,11 @@
 import { prepareVideoData } from './video-utils.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 { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
+import { extractCompletionText, detectReasoningCutoff, buildCompletionMeta, } from './completion-utils.js';
+import { buildCacheHeaders, extractCacheMeta, } from './cache.js';
+import { awaitCompletionWithHeaders } from './openai-withresponse.js';
 /**
  * Default model — `google/gemini-2.5-flash` has the widest video-input
  * support on OpenRouter at time of writing. Override via env
@@ -10,9 +13,8 @@ import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './co
  */
 const FALLBACK_DEFAULT_MODEL = 'google/gemini-2.5-flash';
 export async function handleAnalyzeVideo(request, openai, defaultModel) {
-    const { video_path, question, model } = request.params.arguments ?? {
-        video_path: '',
-    };
+    const args = request.params.arguments ?? { video_path: '' };
+    const { video_path, question, model, cache_input, cache, cache_ttl, cache_clear } = args;
     if (!video_path) {
         return toolError(ErrorCode.INVALID_INPUT, 'video_path is required.');
     }
@@ -37,14 +39,25 @@ export async function handleAnalyzeVideo(request, openai, defaultModel) {
         }
         return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
     }
+    const videoBlock = {
+        // The `video_url` content type is an OpenRouter extension; the OpenAI
+        // SDK's typings don't know about it yet.
+        type: 'video_url',
+        video_url: { url: `data:${videoData.mediaType};base64,${videoData.data}` },
+    };
+    if (cache_input)
+        videoBlock.cache_control = { type: 'ephemeral' };
+    const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
+    const requestOpts = Object.keys(headers).length > 0 ? { headers } : undefined;
     let completion;
+    let responseHeaders;
     try {
         logger.debug('analyze_video.submit', {
             model: pickedModel,
             format: videoData.format,
             size_bytes: videoData.sizeBytes,
         });
-        completion = await openai.chat.completions.create({
+        const call = openai.chat.completions.create({
             model: pickedModel,
             messages: [
                 {
@@ -54,19 +67,14 @@ export async function handleAnalyzeVideo(request, openai, defaultModel) {
                             type: 'text',
                             text: question || 'Describe what happens in this video, step by step.',
                         },
-                        {
-                            // The `video_url` content type is an OpenRouter extension; the
-                            // OpenAI SDK's typings don't know about it yet. See:
-                            // https://openrouter.ai/docs/guides/overview/multimodal/videos
-                            type: 'video_url',
-                            video_url: {
-                                url: `data:${videoData.mediaType};base64,${videoData.data}`,
-                            },
-                        },
+                        videoBlock,
                     ],
                 },
             ],
-        });
+        }, requestOpts);
+        const { data, response } = await awaitCompletionWithHeaders(call);
+        completion = data;
+        responseHeaders = response?.headers;
     }
     catch (err) {
         logger.warn('analyze_video.error', {
@@ -83,11 +91,15 @@ export async function handleAnalyzeVideo(request, openai, defaultModel) {
             finish_reason: extracted.finishReason,
         });
     }
+    const cacheMeta = extractCacheMeta(responseHeaders);
+    const extra = {
+        server_version: SERVER_VERSION,
+        content_is_untrusted: true,
+    };
+    if (cacheMeta)
+        extra.cache = cacheMeta;
     return {
         content: [{ type: 'text', text: extracted.text }],
-        _meta: {
-            finish_reason: extracted.finishReason,
-            ...(toUsageMeta(extracted.usage) ?? {}),
-        },
+        _meta: buildCompletionMeta(extracted, { extra }),
     };
 }

package/dist/tool-handlers/cache.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Response caching helpers for OpenRouter's X-OpenRouter-Cache header family.
+ * See https://openrouter.ai/docs/guides/features/response-caching
+ *
+ * Three caller inputs:
+ *   - cache:       enable caching for this request
+ *   - cache_ttl:   TTL string (1s .. 24h), e.g. "5m", "1h"; pass-through
+ *   - cache_clear: bust the cache entry for this request
+ *
+ * Server-wide default: OPENROUTER_CACHE_RESPONSES=1 enables cache on every
+ * request unless the caller explicitly passes cache=false.
+ */
+export interface CacheOptions {
+    cache?: boolean;
+    cache_ttl?: string;
+    cache_clear?: boolean;
+}
+/** Parse the env-default and return `true` when caching should be on by default. */
+export declare function readCacheDefault(): boolean;
+/**
+ * Build the headers object to pass as the second argument to
+ * `openai.chat.completions.create(body, { headers })`. Returns an empty
+ * object when nothing should be sent, so the caller can always spread the
+ * result without a conditional.
+ */
+export declare function buildCacheHeaders(opts: CacheOptions | undefined): Record<string, string>;
+/** Extract cache metadata from response headers, null when not present. */
+export interface CacheMeta {
+    status: 'HIT' | 'MISS' | string;
+    age?: number;
+    ttl?: string;
+}
+export declare function extractCacheMeta(headers: Headers | undefined): CacheMeta | null;

package/dist/tool-handlers/cache.js

@@ -0,0 +1,54 @@
+/**
+ * Response caching helpers for OpenRouter's X-OpenRouter-Cache header family.
+ * See https://openrouter.ai/docs/guides/features/response-caching
+ *
+ * Three caller inputs:
+ *   - cache:       enable caching for this request
+ *   - cache_ttl:   TTL string (1s .. 24h), e.g. "5m", "1h"; pass-through
+ *   - cache_clear: bust the cache entry for this request
+ *
+ * Server-wide default: OPENROUTER_CACHE_RESPONSES=1 enables cache on every
+ * request unless the caller explicitly passes cache=false.
+ */
+/** Parse the env-default and return `true` when caching should be on by default. */
+export function readCacheDefault() {
+    const raw = (process.env.OPENROUTER_CACHE_RESPONSES ?? '').trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
+/**
+ * Build the headers object to pass as the second argument to
+ * `openai.chat.completions.create(body, { headers })`. Returns an empty
+ * object when nothing should be sent, so the caller can always spread the
+ * result without a conditional.
+ */
+export function buildCacheHeaders(opts) {
+    const headers = {};
+    const defaultOn = readCacheDefault();
+    // Caller-explicit `cache` wins. If unset, fall back to env default.
+    const enabled = opts?.cache ?? defaultOn;
+    if (enabled)
+        headers['X-OpenRouter-Cache'] = 'true';
+    if (opts?.cache_ttl)
+        headers['X-OpenRouter-Cache-TTL'] = opts.cache_ttl;
+    if (opts?.cache_clear)
+        headers['X-OpenRouter-Cache-Clear'] = 'true';
+    return headers;
+}
+export function extractCacheMeta(headers) {
+    if (!headers)
+        return null;
+    const status = headers.get('x-openrouter-cache-status');
+    if (!status)
+        return null;
+    const ageStr = headers.get('x-openrouter-cache-age');
+    const ttl = headers.get('x-openrouter-cache-ttl') ?? undefined;
+    const meta = { status };
+    if (ageStr) {
+        const n = Number(ageStr);
+        if (Number.isFinite(n))
+            meta.age = n;
+    }
+    if (ttl)
+        meta.ttl = ttl;
+    return meta;
+}

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

@@ -1,7 +1,8 @@
 import OpenAI from 'openai';
 import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
 import { type ProviderRoutingOptions } from './provider-routing.js';
-export interface ChatCompletionToolRequest {
+import { type CacheOptions } from './cache.js';
+export interface ChatCompletionToolRequest extends CacheOptions {
     model?: string;
     messages: ChatCompletionMessageParam[];
     temperature?: number;
@@ -12,6 +13,21 @@ export interface ChatCompletionToolRequest {
      * https://openrouter.ai/docs/features/provider-routing
      */
     provider?: ProviderRoutingOptions;
+    /**
+     * Surface the model's chain-of-thought trace on `_meta.reasoning` when
+     * the upstream response carries one (DeepSeek R1, Gemini Thinking,
+     * Claude Opus 4.7). Defaults to `false` or the value of
+     * `OPENROUTER_INCLUDE_REASONING`.
+     */
+    include_reasoning?: boolean;
+    /**
+     * Enable OpenRouter's web-search plugin (Exa-backed). When true, the
+     * plugin fetches current web results and merges them into the prompt.
+     * Billed at $4 / 1000 results.
+     */
+    online?: boolean;
+    /** Max web-search results when `online: true`. Default 5. */
+    web_max_results?: number;
 }
 export declare function handleChatCompletion(request: {
     params: {
@@ -22,7 +38,5 @@ export declare function handleChatCompletion(request: {
         type: "text";
         text: string;
     }[];
-    _meta: {
-        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
-    };
+    _meta: Record<string, unknown>;
 }>;

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

@@ -1,20 +1,28 @@
 import { ErrorCode, toolError } from '../errors.js';
+import { SERVER_VERSION } from '../version.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
-import { extractCompletionText, detectReasoningCutoff, toUsageMeta, } from './completion-utils.js';
+import { extractCompletionText, detectReasoningCutoff, buildCompletionMeta, } from './completion-utils.js';
 import { readProviderDefaults, mergeProviderOptions, buildProviderBody, resolveMaxTokens, } from './provider-routing.js';
+import { buildCacheHeaders, extractCacheMeta, } from './cache.js';
+import { awaitCompletionWithHeaders } from './openai-withresponse.js';
 const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
+function readIncludeReasoningDefault() {
+    const raw = (process.env.OPENROUTER_INCLUDE_REASONING ?? '').trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
 export async function handleChatCompletion(request, openai, defaultModel) {
-    const { messages, model, temperature, max_tokens, provider } = request.params.arguments ?? {
-        messages: [],
-    };
+    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 providerOptions = mergeProviderOptions(readProviderDefaults(), provider);
     const providerBody = buildProviderBody(providerOptions);
     const effectiveMaxTokens = resolveMaxTokens(max_tokens);
-    // Build the request body. `provider` is an OpenRouter extension not in
-    // the OpenAI SDK's types, so we cast to unknown to thread it through.
+    const wantsReasoning = include_reasoning ?? readIncludeReasoningDefault();
+    // Build the request body. Several OpenRouter extensions aren't in the
+    // OpenAI SDK types, so we assemble as `Record<string, unknown>` and cast
+    // at the call site.
     const body = {
         model: model || defaultModel || DEFAULT_MODEL,
         messages,
@@ -24,9 +32,24 @@ export async function handleChatCompletion(request, openai, defaultModel) {
         body.max_tokens = effectiveMaxTokens;
     if (providerBody)
         body.provider = providerBody;
+    if (wantsReasoning)
+        body.include_reasoning = true;
+    if (online) {
+        const plugin = { id: 'web' };
+        if (typeof web_max_results === 'number' && web_max_results > 0) {
+            plugin.max_results = web_max_results;
+        }
+        body.plugins = [plugin];
+    }
+    const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
+    const requestOpts = Object.keys(headers).length > 0 ? { headers } : undefined;
     let completion;
+    let responseHeaders;
     try {
-        completion = (await openai.chat.completions.create(body));
+        const call = openai.chat.completions.create(body, requestOpts);
+        const { data, response } = await awaitCompletionWithHeaders(call);
+        completion = data;
+        responseHeaders = response?.headers;
     }
     catch (err) {
         return classifyUpstreamError(err);
@@ -38,13 +61,18 @@ export async function handleChatCompletion(request, openai, defaultModel) {
     if (!extracted.text) {
         return toolError(ErrorCode.INTERNAL, 'Model returned no textual content.', {
             finish_reason: extracted.finishReason,
+            native_finish_reason: extracted.nativeFinishReason,
         });
     }
+    const cacheMeta = extractCacheMeta(responseHeaders);
+    const extra = { server_version: SERVER_VERSION };
+    if (cacheMeta)
+        extra.cache = cacheMeta;
     return {
         content: [{ type: 'text', text: extracted.text }],
-        _meta: {
-            finish_reason: extracted.finishReason,
-            ...(toUsageMeta(extracted.usage) ?? {}),
-        },
+        _meta: buildCompletionMeta(extracted, {
+            includeReasoning: wantsReasoning,
+            extra,
+        }),
     };
 }

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

@@ -14,6 +14,19 @@ export interface ExtractedText {
     /** True when `text` came from the reasoning trace (not a final answer). */
     reasonedOnly: boolean;
     finishReason: ChatCompletion.Choice['finish_reason'] | undefined;
+    /**
+     * OpenRouter's `native_finish_reason`, when present. Carries the
+     * provider-native value before OpenRouter normalizes it. Surfaced in
+     * `_meta.native_finish_reason` for debuggability.
+     */
+    nativeFinishReason: string | undefined;
+    /**
+     * Raw reasoning trace (content of `reasoning` or joined `reasoning_details`).
+     * Populated whenever the upstream response carried one, even when the
+     * assistant also produced a final `content` answer. Surfaced to callers
+     * via `_meta.reasoning` when they opt in with `include_reasoning: true`.
+     */
+    reasoning?: string;
     usage?: ChatCompletion['usage'];
 }
 export declare function extractCompletionText(completion: ChatCompletion): ExtractedText;
@@ -25,3 +38,19 @@ export declare function extractCompletionText(completion: ChatCompletion): Extra
  */
 export declare function detectReasoningCutoff(extracted: ExtractedText): ToolErrorResult | null;
 export declare function toUsageMeta(usage: ChatCompletion['usage'] | undefined): Record<string, unknown> | undefined;
+/**
+ * Build the common `_meta` shape for chat-completion-derived tools.
+ * Folds in:
+ *  - normalized and native finish reasons (from the choice)
+ *  - optional `reasoning` trace (when the caller opted in)
+ *  - token usage (prompt / completion / total)
+ *  - server version stamp
+ *
+ * Caller can pass `extra` to merge additional keys (cache metadata,
+ * content_is_untrusted, etc.) without repeating this boilerplate.
+ */
+export interface BuildMetaOptions {
+    includeReasoning?: boolean;
+    extra?: Record<string, unknown>;
+}
+export declare function buildCompletionMeta(extracted: ExtractedText, opts?: BuildMetaOptions): Record<string, unknown>;

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

@@ -1,14 +1,45 @@
 import { ErrorCode, toolError } from '../errors.js';
+function extractReasoning(msg) {
+    if (typeof msg.reasoning === 'string' && msg.reasoning.length > 0)
+        return msg.reasoning;
+    if (Array.isArray(msg.reasoning_details) && msg.reasoning_details.length > 0) {
+        const joined = msg.reasoning_details
+            .filter((d) => typeof d.text === 'string')
+            .map((d) => d.text)
+            .join('\n');
+        if (joined.length > 0)
+            return joined;
+    }
+    return undefined;
+}
 export function extractCompletionText(completion) {
     const choice = completion.choices?.[0];
     const msg = choice?.message;
     const finishReason = choice?.finish_reason;
+    // `native_finish_reason` is an OpenRouter extension, not in the OpenAI
+    // SDK types — read it via an unknown-cast.
+    const nativeFinishReason = choice?.native_finish_reason ?? undefined;
     const usage = completion.usage ?? undefined;
-    if (!msg)
-        return { text: '', reasonedOnly: false, finishReason, usage };
-    const { content, reasoning, reasoning_details } = msg;
+    if (!msg) {
+        return {
+            text: '',
+            reasonedOnly: false,
+            finishReason,
+            nativeFinishReason: nativeFinishReason ?? undefined,
+            usage,
+        };
+    }
+    const { content } = msg;
+    const reasoning = extractReasoning(msg);
     if (typeof content === 'string' && content.length > 0) {
-        return { text: content, reasonedOnly: false, finishReason, usage };
+        return {
+            text: content,
+            reasonedOnly: false,
+            finishReason,
+            nativeFinishReason: nativeFinishReason ?? undefined,
+            reasoning,
+            usage,
+        };
     }
     if (Array.isArray(content)) {
         const parts = content
@@ -16,22 +47,33 @@ export function extractCompletionText(completion) {
             .map((p) => p.text ?? '');
         const joined = parts.join('');
         if (joined.length > 0) {
-            return { text: joined, reasonedOnly: false, finishReason, usage };
+            return {
+                text: joined,
+                reasonedOnly: false,
+                finishReason,
+                nativeFinishReason: nativeFinishReason ?? undefined,
+                reasoning,
+                usage,
+            };
         }
     }
-    if (typeof reasoning === 'string' && reasoning.length > 0) {
-        return { text: reasoning, reasonedOnly: true, finishReason, usage };
-    }
-    if (Array.isArray(reasoning_details) && reasoning_details.length > 0) {
-        const joined = reasoning_details
-            .filter((d) => typeof d.text === 'string')
-            .map((d) => d.text)
-            .join('\n');
-        if (joined.length > 0) {
-            return { text: joined, reasonedOnly: true, finishReason, usage };
-        }
+    if (reasoning && reasoning.length > 0) {
+        return {
+            text: reasoning,
+            reasonedOnly: true,
+            finishReason,
+            nativeFinishReason: nativeFinishReason ?? undefined,
+            reasoning,
+            usage,
+        };
     }
-    return { text: '', reasonedOnly: false, finishReason, usage };
+    return {
+        text: '',
+        reasonedOnly: false,
+        finishReason,
+        nativeFinishReason: nativeFinishReason ?? undefined,
+        usage,
+    };
 }
 /**
  * If the extracted response is reasoning-only and was cut off by
@@ -67,3 +109,20 @@ export function toUsageMeta(usage) {
         },
     };
 }
+export function buildCompletionMeta(extracted, opts = {}) {
+    const meta = {
+        finish_reason: extracted.finishReason,
+    };
+    if (extracted.nativeFinishReason) {
+        meta.native_finish_reason = extracted.nativeFinishReason;
+    }
+    if (opts.includeReasoning && extracted.reasoning && !extracted.reasonedOnly) {
+        meta.reasoning = extracted.reasoning;
+    }
+    const usageMeta = toUsageMeta(extracted.usage);
+    if (usageMeta)
+        Object.assign(meta, usageMeta);
+    if (opts.extra)
+        Object.assign(meta, opts.extra);
+    return meta;
+}

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

@@ -41,6 +41,7 @@ export declare function handleGenerateAudio(request: {
         text?: undefined;
     })[];
     _meta: {
+        server_version: string;
         save_path: string;
         mime: string;
         size_bytes: number;
@@ -58,6 +59,7 @@ export declare function handleGenerateAudio(request: {
         text?: undefined;
     })[];
     _meta: {
+        server_version: string;
         mime: string;
         size_bytes: number;
         save_path?: undefined;

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

@@ -2,6 +2,8 @@ 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';
 const DEFAULT_MODEL = 'openai/gpt-audio';
 const DEFAULT_VOICE = 'alloy';
@@ -89,6 +91,16 @@ export async function handleGenerateAudio(request, openai) {
     if (!prompt?.trim()) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
+    // Audit entry. See generate_image for rationale.
+    logger.audit('generate_audio.start', {
+        model: model || DEFAULT_MODEL,
+        voice: voice?.trim() || DEFAULT_VOICE,
+        format: VALID_FORMATS.includes(format ?? '')
+            ? format
+            : DEFAULT_FORMAT,
+        prompt_preview: prompt.slice(0, 80),
+        save_path: save_path ? 'provided' : 'none',
+    });
     // Fail-fast on unsafe paths BEFORE spending tokens.
     let safeBase = null;
     if (save_path) {
@@ -165,6 +177,7 @@ export async function handleGenerateAudio(request, openai) {
                     { type: 'audio', mimeType: detected.mimeType, data: returnBase64 },
                 ],
                 _meta: {
+                    server_version: SERVER_VERSION,
                     save_path: actualSavePath,
                     mime: detected.mimeType,
                     size_bytes: audioBuffer.length,
@@ -176,7 +189,11 @@ 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 },
+            _meta: {
+                server_version: SERVER_VERSION,
+                mime: detected.mimeType,
+                size_bytes: audioBuffer.length,
+            },
         };
     }
     catch (err) {

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

@@ -69,6 +69,7 @@ export declare function handleGenerateImage(request: {
             completion_tokens: number;
             total_tokens: number;
         } | undefined;
+        server_version: string;
         save_path: string;
         mime: string;
     };
@@ -84,6 +85,7 @@ export declare function handleGenerateImage(request: {
             completion_tokens: number;
             total_tokens: number;
         } | undefined;
+        server_version: string;
         mime: string;
     };
 }>;

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

@@ -3,6 +3,8 @@ import path from 'node:path';
 import { resolveSafeOutputPath, resolveSafeInputPath, UnsafeOutputPathError } from './path-safety.js';
 import { parseBase64DataUrl } from './fetch-utils.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
@@ -30,6 +32,17 @@ 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),
+        aspect_ratio,
+        image_size,
+        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)) {
@@ -126,6 +139,7 @@ export async function handleGenerateImage(request, openai) {
                 { type: 'image', mimeType: base64.mime, data: base64.data },
             ],
             _meta: {
+                server_version: SERVER_VERSION,
                 save_path: safePathResolved,
                 mime: base64.mime,
                 ...(usage
@@ -144,6 +158,7 @@ export async function handleGenerateImage(request, openai) {
     return {
         content: [{ type: 'image', mimeType: base64.mime, data: base64.data }],
         _meta: {
+            server_version: SERVER_VERSION,
             mime: base64.mime,
             ...(usage
                 ? {

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

@@ -39,6 +39,7 @@ export declare function handleGenerateVideo(request: {
     }[];
     isError: false;
     _meta: {
+        server_version: string;
         code: "JOB_STILL_RUNNING";
         video_id: string;
         polling_url: string;
@@ -64,12 +65,54 @@ export declare function handleGetVideoStatus(request: {
     }[];
     isError: false;
     _meta: {
+        server_version: string;
         code: "JOB_STILL_RUNNING";
         video_id: string;
         last_status: string;
         progress: number | undefined;
     };
 }>;
+/**
+ * Image-to-video convenience wrapper. Takes a single `image` argument
+ * (first frame) and delegates to `handleGenerateVideo` with the broader
+ * parameter surface hidden. Based on arxiv 2511.03497's finding that
+ * tool-calling success degrades with parameter count — a narrower tool
+ * gives the model a cleaner decision path.
+ */
+export interface GenerateVideoFromImageRequest {
+    image: string;
+    prompt: string;
+    model?: string;
+    resolution?: string;
+    aspect_ratio?: string;
+    duration?: number;
+    seed?: number;
+    save_path?: string;
+    max_wait_ms?: number;
+    poll_interval_ms?: number;
+}
+export declare function handleGenerateVideoFromImage(request: {
+    params: {
+        arguments: GenerateVideoFromImageRequest;
+    };
+}, apiClient: OpenRouterAPIClient, progress?: ProgressHook): Promise<import("../errors.js").ToolErrorResult | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: false;
+    _meta: {
+        server_version: string;
+        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 const _internals: {
     buildRequestBody: typeof buildRequestBody;
     stripAndReplaceExt: typeof stripAndReplaceExt;