@stabgan/openrouter-mcp-multimodal 4.0.1 → 4.5.0

package/README.md

@@ -92,6 +92,12 @@ Install-link audit (2026-04-20, round 4 — HTTPS redirectors only):
 | Image generation | ✅ Path-sandboxed disk output |
 | **Video understanding** | ✅ **v3** — mp4, mpeg, mov, webm from files, URLs, or data URLs |
 | **Video generation** | ✅ **v3** — Veo 3.1 / Sora 2 Pro / Seedance / Wan via async API with progress notifications |
+| **Response caching** | ✅ **v4.5** — `X-OpenRouter-Cache` passthrough, zero tokens billed on hit, 80–300ms latency |
+| **Web search plugin** | ✅ **v4.5** — `online: true` on `chat_completion` injects OpenRouter's Exa-backed plugin |
+| **Rerank** | ✅ **v4.5** — `rerank_documents` tool against `/rerank` (Cohere, Fireworks) |
+| **Health check** | ✅ **v4.5** — `health_check` verifies API key + OpenRouter reachability |
+| **Reasoning tokens** | ✅ **v4.5** — passthrough of DeepSeek R1 / Gemini Thinking / Opus 4.7 traces on `_meta.reasoning` |
+| **MCP 2025-06-18 spec** | ✅ **v4.5** — structured outputs (`outputSchema`), progress notifications, `title` + `openWorldHint` |
 | Auto image resize + compress | ✅ Configurable (defaults 800px max, JPEG 80%) |
 | Model search + validation | ✅ Filter by vision / audio / video modality |
 | Free model support | ✅ Default: free Nemotron VL |
@@ -106,17 +112,20 @@ Install-link audit (2026-04-20, round 4 — HTTPS redirectors only):
 
 | Tool | Description |
 | :--- | :--- |
-| `chat_completion` | Send messages to any OpenRouter model. Detects reasoning-model cutoffs. Supports **provider routing** (`quantizations`, `ignore`, `sort`, `order`, `require_parameters`, `data_collection`, `allow_fallbacks`) and **model suffixes** (`:nitro` for fastest, `:floor` for cheapest). |
-| `analyze_image` | Analyze images from local files, URLs, or data URIs. Auto-optimized with sharp. |
-| `analyze_audio` | Analyze/transcribe audio (WAV, MP3, FLAC, OGG, etc.) from files, URLs, or data URIs. |
-| `analyze_video` | Analyze/transcribe video (mp4, mpeg, mov, webm) from files, URLs, or data URIs. |
+| `chat_completion` | Send messages to any OpenRouter model. Detects reasoning-model cutoffs. Supports **provider routing** (`quantizations`, `ignore`, `sort`, `order`, `require_parameters`, `data_collection`, `allow_fallbacks`), **model suffixes** (`:nitro` for fastest, `:floor` for cheapest, `:exacto` for Auto Exacto tool-calling), **response caching** (`cache`, `cache_ttl`, `cache_clear`), **reasoning passthrough** (`include_reasoning`), and **web search** (`online`, `web_max_results`). |
+| `analyze_image` | Analyze images from local files, URLs, or data URIs. Auto-optimized with sharp. Optional `cache_input: true` attaches `cache_control: ephemeral` for Anthropic / Gemini 2.5+ prompt caching. |
+| `analyze_audio` | Analyze/transcribe audio (WAV, MP3, FLAC, OGG, etc.) from files, URLs, or data URIs. Optional `cache_input: true` for prompt caching. |
+| `analyze_video` | Analyze/transcribe video (mp4, mpeg, mov, webm) from files, URLs, or data URIs. Optional `cache_input: true` for prompt caching. |
 | `generate_image` | Generate images from text prompts. Supports `aspect_ratio` (14 values), `image_size` (0.5K–4K), and `max_tokens`. Optional path-sandboxed disk save. |
 | `generate_audio` | Generate audio from text. Auto-detects format, wraps raw PCM in WAV. |
-| `generate_video` | Generate video via OpenRouter's async API (Veo 3.1 / Sora 2 Pro / Seedance / Wan). Submits, polls, downloads, saves. |
+| `generate_video` | Generate video via OpenRouter's async API (Veo 3.1 / Sora 2 Pro / Seedance / Wan). Submits, polls, downloads, saves. Emits MCP `notifications/progress` when the client sends a `progressToken`. |
+| `generate_video_from_image` | Image-to-video wrapper around `generate_video`. Narrower schema, higher tool-call hit rate. |
 | `get_video_status` | Resume polling a `generate_video` job by id. Download + save when complete. |
-| `search_models` | Search/filter models by name, provider, or capabilities (vision / audio / video). |
+| `rerank_documents` | Rerank candidate documents against a query via OpenRouter's `/rerank` endpoint. Supports Cohere and Fireworks rerankers. |
+| `search_models` | Search/filter models by name, provider, or capabilities (vision / audio / video). Paginated via `offset` / `next_offset` / `has_more` / `total`. |
 | `get_model_info` | Get pricing, context length, and capabilities for any model. |
 | `validate_model` | Check if a model ID exists on OpenRouter. |
+| `health_check` | Verify API-key validity, OpenRouter reachability, and return server + protocol versions. |
 
 > All error responses carry `_meta.code` from a closed taxonomy: `INVALID_INPUT` · `UNSAFE_PATH` · `UPSTREAM_HTTP` · `UPSTREAM_TIMEOUT` · `UPSTREAM_REFUSED` · `UNSUPPORTED_FORMAT` · `RESOURCE_TOO_LARGE` · `ZDR_INCOMPATIBLE` · `MODEL_NOT_FOUND` · `JOB_FAILED` · `JOB_STILL_RUNNING` · `INTERNAL`
 
@@ -200,6 +209,8 @@ npx -y @smithery/cli install @stabgan/openrouter-mcp-multimodal --client claude
 | `OPENROUTER_PROVIDER_REQUIRE_PARAMETERS` | No | — | `true` / `false`. Only use providers supporting every request parameter. |
 | `OPENROUTER_PROVIDER_DATA_COLLECTION` | No | — | `allow` / `deny`. Opt out of providers that log request data. |
 | `OPENROUTER_PROVIDER_ALLOW_FALLBACKS` | No | — | `true` / `false`. |
+| `OPENROUTER_CACHE_RESPONSES` | No | — | `1` / `true`. Enable response caching server-wide. Sends `X-OpenRouter-Cache: true` on chat + analyze_* calls unless overridden per-request with `cache: false`. Zero tokens billed on hits. |
+| `OPENROUTER_INCLUDE_REASONING` | No | — | `1` / `true`. Enable reasoning tokens passthrough server-wide for DeepSeek R1 / Gemini Thinking / Opus 4.7. Adds `_meta.reasoning` to `chat_completion` responses. |
 | `OPENROUTER_MODEL_CACHE_TTL_MS` | No | `3600000` | Model cache TTL (ms) |
 | `OPENROUTER_IMAGE_MAX_DIMENSION` | No | `800` | Longest edge for resize (px) |
 | `OPENROUTER_IMAGE_JPEG_QUALITY` | No | `80` | JPEG quality (1–100) |
@@ -249,6 +260,28 @@ Use chat_completion with model "openai/gpt-4o:nitro", prompt "Reason step-by-ste
 # Chat with :floor variant for cheapest provider of the requested model
 Use chat_completion with model "mistralai/mistral-7b-instruct:floor", prompt "Quick check"
 
+# Chat with response caching + reasoning passthrough (v4.5)
+Use chat_completion with model "deepseek/deepseek-r1", prompt "Prove sqrt(2) is irrational",
+cache: true, cache_ttl: 3600, include_reasoning: true
+# → response.meta.cache = { status: "hit" | "miss", age, ttl }
+# → response.meta.reasoning = "<upstream reasoning trace>"
+
+# Chat with web search plugin (v4.5)
+Use chat_completion with model "openai/gpt-4o", prompt "What shipped in OpenRouter last week?",
+online: true, web_max_results: 5
+
+# Rerank documents against a query (v4.5)
+Use rerank_documents with query "best practices for MCP server auth",
+documents: ["doc A text...", "doc B text...", "doc C text..."], top_n: 3
+
+# Generate video from an image (v4.5)
+Use generate_video_from_image with image "./frame.png", prompt "zoom out slowly",
+model "google/veo-3.1", save to ./clip.mp4
+
+# Health check (v4.5)
+Use health_check
+# → { ok: true, server_version: "4.5.0", protocol_version: "2025-06-18", api_key_valid: true, models_cached: 312 }
+
 # Vision
 Use analyze_image on /path/to/photo.jpg and tell me what you see.
 
@@ -339,7 +372,7 @@ Works with any MCP client: [Kiro](https://kiro.dev) · [Claude Desktop](https://
 
 ## License
 
-Apache 2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE). v1.0.0 through v3.2.0 were released under MIT; v4.0.0 relicensed to Apache 2.0 (Apache 2.0 is a permissive superset of MIT with explicit patent grant).
+Apache 2.0. See [LICENSE](./LICENSE). v1.0.0 through v3.2.0 were released under MIT; v4.0.0 relicensed to Apache 2.0 (Apache 2.0 is a permissive superset of MIT with explicit patent grant).
 
 ## Contributing
 

package/dist/errors.d.ts

@@ -1,7 +1,7 @@
 /**
  * Closed error-code taxonomy for MCP tool responses. Every handler uses
- * `toolError(code, message, details?)` instead of ad-hoc text so clients
- * can switch on `_meta.code` without regex-parsing free text.
+ * `toolError(code, message, details?, opts?)` instead of ad-hoc text so
+ * clients can switch on `_meta.code` without regex-parsing free text.
  *
  * Adding a new code requires a design.md note — this set is intentionally
  * small and stable.
@@ -21,22 +21,40 @@ export declare const ErrorCode: {
     readonly INTERNAL: "INTERNAL";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+export interface ToolErrorMeta {
+    code: ErrorCode;
+    details?: Record<string, unknown>;
+    /**
+     * Optional human-readable next steps the agent can take. Inspired by
+     * the Apigene "structured errors" best practice: rather than a raw
+     * string for the agent to interpret, list concrete options like
+     * "Wait and retry" or "Lower resolution to 480p".
+     */
+    suggestions?: string[];
+    /**
+     * For rate-limit / backoff errors, the number of seconds the caller
+     * should wait before retrying. Derived from `Retry-After` headers when
+     * available.
+     */
+    retry_after_seconds?: number;
+}
 export interface ToolErrorResult {
     content: Array<{
         type: 'text';
         text: string;
     }>;
     isError: true;
-    _meta: {
-        code: ErrorCode;
-        details?: Record<string, unknown>;
-    };
+    _meta: ToolErrorMeta;
+}
+export interface ToolErrorOptions {
+    suggestions?: string[];
+    retry_after_seconds?: number;
 }
 /** Build a structured MCP error result. */
-export declare function toolError(code: ErrorCode, message: string, details?: Record<string, unknown>): ToolErrorResult;
+export declare function toolError(code: ErrorCode, message: string, details?: Record<string, unknown>, opts?: ToolErrorOptions): ToolErrorResult;
 /**
  * Convert a caught `unknown` error into a structured tool result. Preserves
  * user-visible messages for known `Error` types and refuses to leak stack
  * traces or raw objects.
  */
-export declare function toolErrorFrom(code: ErrorCode, err: unknown, prefix?: string): ToolErrorResult;
+export declare function toolErrorFrom(code: ErrorCode, err: unknown, prefix?: string, opts?: ToolErrorOptions): ToolErrorResult;

package/dist/errors.js

@@ -1,7 +1,7 @@
 /**
  * Closed error-code taxonomy for MCP tool responses. Every handler uses
- * `toolError(code, message, details?)` instead of ad-hoc text so clients
- * can switch on `_meta.code` without regex-parsing free text.
+ * `toolError(code, message, details?, opts?)` instead of ad-hoc text so
+ * clients can switch on `_meta.code` without regex-parsing free text.
  *
  * Adding a new code requires a design.md note — this set is intentionally
  * small and stable.
@@ -21,26 +21,31 @@ export const ErrorCode = {
     INTERNAL: 'INTERNAL',
 };
 /** Build a structured MCP error result. */
-export function toolError(code, message, details) {
-    const result = {
+export function toolError(code, message, details, opts) {
+    const meta = { code };
+    if (details !== undefined)
+        meta.details = details;
+    if (opts?.suggestions && opts.suggestions.length > 0)
+        meta.suggestions = opts.suggestions;
+    if (typeof opts?.retry_after_seconds === 'number') {
+        meta.retry_after_seconds = opts.retry_after_seconds;
+    }
+    return {
         content: [{ type: 'text', text: message }],
         isError: true,
-        _meta: { code },
+        _meta: meta,
     };
-    if (details !== undefined)
-        result._meta.details = details;
-    return result;
 }
 /**
  * Convert a caught `unknown` error into a structured tool result. Preserves
  * user-visible messages for known `Error` types and refuses to leak stack
  * traces or raw objects.
  */
-export function toolErrorFrom(code, err, prefix) {
+export function toolErrorFrom(code, err, prefix, opts) {
     const base = prefix ? `${prefix}: ` : '';
     if (err instanceof Error)
-        return toolError(code, base + err.message);
+        return toolError(code, base + err.message, undefined, opts);
     if (typeof err === 'string')
-        return toolError(code, base + err);
-    return toolError(code, base + 'unknown error');
+        return toolError(code, base + err, undefined, opts);
+    return toolError(code, base + 'unknown error', undefined, opts);
 }

package/dist/logger.d.ts

@@ -7,6 +7,10 @@
  *
  * Level is filtered by OPENROUTER_LOG_LEVEL (error|warn|info|debug,
  * default info). Unknown values fall through to info.
+ *
+ * `audit` is a special level that ALWAYS writes (bypasses the level filter),
+ * intended for cost-incurring / destructive operations so operators can
+ * trace them after the fact.
  */
 export type LogLevel = 'error' | 'warn' | 'info' | 'debug';
 /** Low-level write hook, replaceable in tests. */
@@ -19,4 +23,11 @@ export declare const logger: {
     warn: (msg: string, ctx?: Record<string, unknown>) => void;
     info: (msg: string, ctx?: Record<string, unknown>) => void;
     debug: (msg: string, ctx?: Record<string, unknown>) => void;
+    /**
+     * Always-on audit line. Bypasses OPENROUTER_LOG_LEVEL. Use for paid or
+     * destructive operations (generate_video, generate_audio, generate_image)
+     * so operators can trace unintended spend via `docker logs` or a log
+     * aggregator.
+     */
+    audit(msg: string, ctx?: Record<string, unknown>): void;
 };

package/dist/logger.js

@@ -44,4 +44,30 @@ export const logger = {
     warn: (msg, ctx) => log('warn', msg, ctx),
     info: (msg, ctx) => log('info', msg, ctx),
     debug: (msg, ctx) => log('debug', msg, ctx),
+    /**
+     * Always-on audit line. Bypasses OPENROUTER_LOG_LEVEL. Use for paid or
+     * destructive operations (generate_video, generate_audio, generate_image)
+     * so operators can trace unintended spend via `docker logs` or a log
+     * aggregator.
+     */
+    audit(msg, ctx) {
+        const record = {
+            ts: new Date().toISOString(),
+            level: 'audit',
+            msg,
+        };
+        if (ctx)
+            record.ctx = ctx;
+        try {
+            _sink.write(JSON.stringify(record));
+        }
+        catch {
+            _sink.write(JSON.stringify({
+                ts: new Date().toISOString(),
+                level: 'audit',
+                msg,
+                ctx: { note: 'unserializable' },
+            }));
+        }
+    },
 };

package/dist/model-cache.d.ts

@@ -23,6 +23,8 @@ export declare class ModelCache {
      */
     ensureFresh(fetcher: () => Promise<OpenRouterModelRecord[]>): Promise<void>;
     getAll(): OpenRouterModelRecord[];
+    /** Number of models currently cached. Used by health_check. */
+    size(): number;
     get(id: string): OpenRouterModelRecord | null;
     has(id: string): boolean;
     search(params: {
@@ -34,5 +36,7 @@ export declare class ModelCache {
             video?: boolean;
         };
         limit?: number;
+        /** When true, return the full filtered set and ignore `limit`. Used by pagination. */
+        all?: boolean;
     }): OpenRouterModelRecord[];
 }

package/dist/model-cache.js

@@ -45,6 +45,10 @@ export class ModelCache {
     getAll() {
         return Object.values(this.models);
     }
+    /** Number of models currently cached. Used by health_check. */
+    size() {
+        return Object.keys(this.models).length;
+    }
     get(id) {
         return this.models[id] ?? null;
     }
@@ -70,6 +74,8 @@ export class ModelCache {
         if (params.capabilities?.video) {
             results = results.filter((m) => m.architecture?.input_modalities?.includes('video'));
         }
+        if (params.all)
+            return results;
         const limit = Math.min(Math.max(1, params.limit ?? 10), MAX_SEARCH_LIMIT);
         return results.slice(0, limit);
     }

package/dist/openrouter-api.d.ts

@@ -21,8 +21,7 @@ export declare class OpenRouterAPIClient {
     submitVideoJob(body: Record<string, unknown>): Promise<VideoJobEnvelope>;
     /** Poll a submitted video-generation job by id. */
     pollVideoJob(id: string): Promise<VideoJobStatus>;
-    /**
-     * Download the generated video binary. Returns `{ buffer, contentType }`.
+    /** Download the generated video binary. Returns `{ buffer, contentType }`.
      * This intentionally does NOT go through our SSRF-guarded `fetchHttpResource`
      * because the URL is always OpenRouter itself (trusted origin) — and it can
      * return arbitrarily large bodies that the caller bounds via
@@ -32,6 +31,13 @@ export declare class OpenRouterAPIClient {
         buffer: Buffer;
         contentType: string | null;
     }>;
+    /** POST /rerank — re-order documents by relevance to a query. */
+    rerank(params: {
+        model: string;
+        query: string;
+        documents: string[];
+        top_n?: number;
+    }): Promise<RerankResponse>;
 }
 export interface VideoJobEnvelope {
     id: string;
@@ -39,6 +45,20 @@ export interface VideoJobEnvelope {
     polling_url?: string;
     [key: string]: unknown;
 }
+export interface RerankResultItem {
+    index: number;
+    relevance_score?: number;
+    score?: number;
+    document?: {
+        text?: string;
+    } | string;
+}
+export interface RerankResponse {
+    model?: string;
+    results: RerankResultItem[];
+    usage?: Record<string, unknown>;
+    [key: string]: unknown;
+}
 export type VideoJobStatusName = 'pending' | 'queued' | 'processing' | 'completed' | 'failed';
 export interface VideoJobStatus {
     id: string;

package/dist/openrouter-api.js

@@ -104,8 +104,7 @@ export class OpenRouterAPIClient {
         }
         return (await res.json());
     }
-    /**
-     * Download the generated video binary. Returns `{ buffer, contentType }`.
+    /** Download the generated video binary. Returns `{ buffer, contentType }`.
      * This intentionally does NOT go through our SSRF-guarded `fetchHttpResource`
      * because the URL is always OpenRouter itself (trusted origin) — and it can
      * return arbitrarily large bodies that the caller bounds via
@@ -152,6 +151,26 @@ export class OpenRouterAPIClient {
         }
         return { buffer: Buffer.concat(chunks), contentType: res.headers.get('content-type') };
     }
+    /** POST /rerank — re-order documents by relevance to a query. */
+    async rerank(params) {
+        const body = {
+            model: params.model,
+            query: params.query,
+            documents: params.documents,
+        };
+        if (typeof params.top_n === 'number' && params.top_n > 0)
+            body.top_n = params.top_n;
+        const res = await fetchWithRetry(`${BASE_URL}/rerank`, {
+            method: 'POST',
+            headers: this.authHeaders({ 'Content-Type': 'application/json' }),
+            body: JSON.stringify(body),
+        }, { retries: 2, timeoutMs: DEFAULT_TIMEOUT_MS });
+        if (!res.ok) {
+            const detail = await safeReadText(res);
+            throw new Error(`POST /rerank failed: HTTP ${res.status}${detail ? ` — ${detail}` : ''}`);
+        }
+        return (await res.json());
+    }
 }
 async function safeReadText(res) {
     try {

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

@@ -1,8 +1,15 @@
 import OpenAI from 'openai';
-export interface AnalyzeAudioToolRequest {
+import { type CacheOptions } from './cache.js';
+export interface AnalyzeAudioToolRequest extends CacheOptions {
     audio_path: string;
     question?: string;
     model?: string;
+    /**
+     * Attach `cache_control: {type: 'ephemeral'}` to the audio block so
+     * Claude / Gemini 2.5+ prompt-caches it. Repeat questions about the
+     * same audio then cost dramatically less for the audio portion.
+     */
+    cache_input?: boolean;
 }
 export declare function handleAnalyzeAudio(request: {
     params: {
@@ -13,7 +20,5 @@ export declare function handleAnalyzeAudio(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/analyze-audio.js

@@ -1,10 +1,14 @@
 import { prepareAudioData } from './audio-utils.js';
 import { ErrorCode, toolError, toolErrorFrom } 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 { buildCacheHeaders, extractCacheMeta, } from './cache.js';
+import { awaitCompletionWithHeaders } from './openai-withresponse.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash';
 export async function handleAnalyzeAudio(request, openai, defaultModel) {
-    const { audio_path, question, model } = request.params.arguments ?? { audio_path: '' };
+    const args = request.params.arguments ?? { audio_path: '' };
+    const { audio_path, question, model, cache_input, cache, cache_ttl, cache_clear } = args;
     if (!audio_path) {
         return toolError(ErrorCode.INVALID_INPUT, 'audio_path is required.');
     }
@@ -24,26 +28,32 @@ export async function handleAnalyzeAudio(request, openai, defaultModel) {
         }
         return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
     }
+    const audioBlock = {
+        type: 'input_audio',
+        input_audio: { data: audioData.data, format: audioData.format },
+    };
+    if (cache_input)
+        audioBlock.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 {
-        completion = await openai.chat.completions.create({
+        const call = openai.chat.completions.create({
             model: model || defaultModel || DEFAULT_MODEL,
             messages: [
                 {
                     role: 'user',
                     content: [
                         { type: 'text', text: question || 'Please transcribe and analyze this audio file.' },
-                        {
-                            type: 'input_audio',
-                            input_audio: {
-                                data: audioData.data,
-                                format: audioData.format,
-                            },
-                        },
+                        audioBlock,
                     ],
                 },
             ],
-        });
+        }, requestOpts);
+        const { data, response } = await awaitCompletionWithHeaders(call);
+        completion = data;
+        responseHeaders = response?.headers;
     }
     catch (err) {
         return classifyUpstreamError(err);
@@ -57,11 +67,15 @@ export async function handleAnalyzeAudio(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/analyze-image.d.ts

@@ -1,8 +1,16 @@
 import OpenAI from 'openai';
-export interface AnalyzeImageToolRequest {
+import { type CacheOptions } from './cache.js';
+export interface AnalyzeImageToolRequest extends CacheOptions {
     image_path: string;
     question?: string;
     model?: string;
+    /**
+     * When true, attach Anthropic-style `cache_control: {type: 'ephemeral'}`
+     * to the image block so Claude / Gemini 2.5+ prompt-caches it. Repeat
+     * questions about the same image then cost ~0.1x on Anthropic and
+     * ~0.25x on Gemini for the image input.
+     */
+    cache_input?: boolean;
 }
 export declare function handleAnalyzeImage(request: {
     params: {
@@ -13,7 +21,5 @@ export declare function handleAnalyzeImage(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/analyze-image.js

@@ -1,10 +1,14 @@
 import { prepareImageUrl } from './image-utils.js';
 import { ErrorCode, toolError, toolErrorFrom } 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 { buildCacheHeaders, extractCacheMeta, } 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) {
-    const { image_path, question, model } = request.params.arguments ?? { image_path: '' };
+    const args = request.params.arguments ?? { image_path: '' };
+    const { image_path, question, model, cache_input, cache, cache_ttl, cache_clear } = args;
     if (!image_path) {
         return toolError(ErrorCode.INVALID_INPUT, 'image_path is required.');
     }
@@ -21,20 +25,35 @@ export async function handleAnalyzeImage(request, openai, defaultModel) {
         }
         return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
     }
+    // Attach `cache_control` to the image block when requested. The openai
+    // SDK doesn't type this field but passes it through to the server,
+    // which forwards it to providers that support prompt caching.
+    const imageBlock = {
+        type: 'image_url',
+        image_url: { url: imageUrl },
+    };
+    if (cache_input)
+        imageBlock.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 {
-        completion = await openai.chat.completions.create({
+        const call = openai.chat.completions.create({
             model: model || defaultModel || DEFAULT_MODEL,
             messages: [
                 {
                     role: 'user',
                     content: [
                         { type: 'text', text: question || "What's in this image?" },
-                        { type: 'image_url', image_url: { url: imageUrl } },
+                        imageBlock,
                     ],
                 },
             ],
-        });
+        }, requestOpts);
+        const { data, response } = await awaitCompletionWithHeaders(call);
+        completion = data;
+        responseHeaders = response?.headers;
     }
     catch (err) {
         return classifyUpstreamError(err);
@@ -48,11 +67,20 @@ export async function handleAnalyzeImage(request, openai, defaultModel) {
             finish_reason: extracted.finishReason,
         });
     }
+    const cacheMeta = extractCacheMeta(responseHeaders);
+    // Output originates from model interpretation of potentially
+    // attacker-controlled image content (typography attacks, QR codes,
+    // adversarial watermarks). Flag it so downstream agents know to treat
+    // this text as data, not instructions. Inspired by ClawGuard (arxiv
+    // 2604.11790) and tool-result-parsing defenses (2601.04795).
+    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/analyze-video.d.ts

@@ -1,8 +1,15 @@
 import OpenAI from 'openai';
-export interface AnalyzeVideoToolRequest {
+import { type CacheOptions } from './cache.js';
+export interface AnalyzeVideoToolRequest extends CacheOptions {
     video_path: string;
     question?: string;
     model?: string;
+    /**
+     * Attach `cache_control: {type: 'ephemeral'}` to the video block so
+     * Claude / Gemini 2.5+ prompt-caches it. Very valuable for large
+     * videos where repeat questions save 10x on Anthropic pricing.
+     */
+    cache_input?: boolean;
 }
 export declare function handleAnalyzeVideo(request: {
     params: {
@@ -13,7 +20,5 @@ export declare function handleAnalyzeVideo(request: {
         type: "text";
         text: string;
     }[];
-    _meta: {
-        finish_reason: "length" | "stop" | "tool_calls" | "content_filter" | "function_call" | undefined;
-    };
+    _meta: Record<string, unknown>;
 }>;