@stabgan/openrouter-mcp-multimodal 4.0.1 → 4.5.1

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.
 
@@ -280,7 +313,7 @@ Use get_video_status with video_id "vid_abc123" and save_path "./river.mp4"
 ```
 src/
 ├── index.ts                    # Entry, env validation, graceful shutdown
-├── tool-handlers.ts            # 11 tools (annotated) + dispatch
+├── tool-handlers.ts            # 14 tools (annotated) + dispatch
 ├── model-cache.ts              # TTL + in-flight coalescing
 ├── openrouter-api.ts           # REST client (chat + /videos)
 ├── errors.ts                   # Closed ErrorCode enum
@@ -305,6 +338,60 @@ src/
     └── validate-model.ts       # Model existence check
 ```
 
+## Design Principles & Research
+
+v4.5.0's design draws from three threads of research and industry guidance. Rather than building in isolation, every feature ties to a cited source so decisions can be re-examined later.
+
+### MCP-first design principles
+
+We follow [Phil Schmid's production guide for MCP servers](https://www.philschmid.de/mcp-best-practices) (Jan 2026), which argues that an MCP server is "a user interface for AI agents, not a REST API wrapper":
+
+- **Outcomes, not operations.** Our tools like `analyze_image` and `generate_video` encapsulate a whole workflow (fetch, validate, invoke, save) rather than exposing raw OpenRouter primitives.
+- **Flattened arguments.** Top-level primitives with enums (`aspect_ratio`, `image_size`), no deeply nested configuration blobs. The one nested object (`provider`) is required by OpenRouter's routing schema.
+- **Descriptions are context.** Every tool description includes "Fails when:" and "Works with:" sections (see next section for the research backing).
+- **Curated surface.** 14 tools total. Each is a distinct outcome; no "helper" tools that exist only for internal composition.
+
+Apigene's ["12 Rules for Production MCP Deployment"](https://apigene.ai/blog/mcp-best-practices) (March 2026) guided the error-handling posture: structured errors with `suggestions` and `retry_after_seconds` on `_meta` beat raw error strings the agent has to interpret.
+
+### MCP 2025-06-18 spec compliance
+
+- **Structured outputs.** `validate_model`, `get_model_info`, `search_models`, `rerank_documents`, and `health_check` emit [`structuredContent` with `outputSchema`](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#output-schema), per §5.2.6-7. Agents can validate responses typefully.
+- **Progress notifications.** `generate_video` emits [`notifications/progress`](https://modelcontextprotocol.io/specification/2025-06-18/basic/utilities/progress) on every poll tick when the client passes a `progressToken` in `_meta`. Progress values are guaranteed strictly monotonic per spec.
+- **Tool annotations.** Every tool carries `title` + `readOnlyHint` + `destructiveHint` + `idempotentHint` + `openWorldHint` so clients can render appropriate UI affordances.
+
+### Research-backed tool-design decisions
+
+These papers shaped specific v4.5.0 choices:
+
+| Finding | Source | How it shaped v4.5.0 |
+| :--- | :--- | :--- |
+| Failure-mode docs and inter-tool relationships measurably improve tool-selection accuracy | [Schlapbach, *Convergence of SGD & MCP*](https://arxiv.org/abs/2602.18764) (Feb 2026) | Every tool description has explicit "Fails when:" (ErrorCode triggers) and "Works with:" (related tools). |
+| Tool-call success drops with parameter count and schema complexity | [Fu et al., *ROSBag MCP Server*](https://arxiv.org/abs/2511.03497) (Nov 2025) | `generate_video_from_image` is a narrower image-to-video wrapper around `generate_video` — fewer params, higher hit rate. |
+| Indirect prompt injection via tool-returned content is a real attack vector | [Zhao et al., *ClawGuard*](https://arxiv.org/abs/2604.11790) (Apr 2026) · [Yu et al., *Defense via Tool Result Parsing*](https://arxiv.org/abs/2601.04795) (Jan 2026) | `analyze_image` / `analyze_audio` / `analyze_video` tag their output `_meta.content_is_untrusted: true`. Downstream agents know to treat that text as data, not instructions. |
+| Provider-level tool-calling variance is large and persists across providers for the same model | [OpenRouter Auto Exacto announcement](https://openrouter.ai/announcements/auto-exacto) (Mar 2026) | `chat_completion` documents the `:exacto` model suffix alongside `:nitro` / `:floor`. 80-88% error reduction on top tool-calling models. |
+| LLM JSON defects compound at scale | [OpenRouter Response Healing](https://openrouter.ai/announcements/response-healing-reduce-json-defects-by-80percent) (Dec 2025) | Structured outputs + outputSchema declarations give clients a parseable contract. (Response-healing plugin itself is opt-in on OpenRouter's side.) |
+| MCP servers are vulnerable to preference-manipulation and tool-poisoning attacks | [Wang et al., *MPMA*](https://arxiv.org/abs/2505.11154) (May 2025) · [Turgut & Gümüş, *CASCADE*](https://arxiv.org/abs/2604.17125) (Apr 2026) | Tool descriptions audited for injection surface; audit logging (`logger.audit()`) captures every paid-op invocation with a prompt preview for forensics. |
+
+### OpenRouter platform parity
+
+v4.5.0 surfaces platform features shipped between Q4 2025 and Q2 2026:
+
+- [Response caching via `X-OpenRouter-Cache`](https://openrouter.ai/announcements/response-caching) (Apr 2026): zero tokens billed on identical request cache hits, 80-300ms latency.
+- [Web search plugin](https://openrouter.ai/announcements/introducing-web-search-via-the-api) (Jan 2025): Exa-backed, enabled via `online: true`.
+- [Reasoning tokens](https://openrouter.ai/announcements/reasoning-tokens-for-thinking-models) (Jan 2025): DeepSeek R1 / Gemini Thinking / Opus 4.7 chain-of-thought via `include_reasoning: true`.
+- [Auto Exacto](https://openrouter.ai/announcements/auto-exacto) (Mar 2026): on-by-default for tool-calling; `:exacto` suffix for all other requests.
+- [Rerank endpoint](https://openrouter.ai/announcements/april-release-spotlight) (Apr 2026): Cohere + Fireworks via the new `rerank_documents` tool.
+- [Prompt caching with `cache_control`](https://openrouter.ai/docs/guides/best-practices/prompt-caching): Anthropic Claude 10x / Gemini 2.5+ 4x savings on repeated input media via `cache_input: true` on analyze_* tools.
+- [Zero completion token insurance](https://openrouter.ai/announcements/never-pay-for-empty-ai-responses-again) (Mar 2025): automatic, no opt-in needed.
+
+### Security posture
+
+- **Path sandbox.** All file writes (`save_path`) and reads (`input_images`, frame images) go through `resolveSafeOutputPath` / `resolveSafeInputPath`, which reject traversal escapes. Legacy bypass: `OPENROUTER_ALLOW_UNSAFE_PATHS=1`.
+- **SSRF blocklist.** Loopback, private, link-local, multicast, 6to4, Teredo, ORCHID, and IPv4-mapped IPv6 all rejected at the fetch layer.
+- **Audit logging.** `logger.audit()` emits a JSON line at level=audit for every `generate_video`, `generate_audio`, and `generate_image` call. Bypasses `OPENROUTER_LOG_LEVEL` so unintended spend is always traceable. 80-char prompt preview is the hard PII boundary.
+- **Structured errors.** Closed `_meta.code` taxonomy means agents switch on failure modes without regex-parsing free text. Rate-limit errors include `retry_after_seconds` derived from `Retry-After` headers.
+- **No credential leakage.** `OPENROUTER_API_KEY` is read once at startup, passed to the SDK, and never echoed in logs, tool responses, or error messages. Fatal-error logging whitelists fields explicitly (name / message / trimmed stack) — no raw error objects. Verified by an independent bug-hunter audit (Apr 2026).
+
 ## Development
 
 ```bash
@@ -339,7 +426,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/index.js

@@ -5,14 +5,30 @@ config(); // Load .env file if present
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ToolHandlers } from './tool-handlers.js';
+import { logger } from './logger.js';
+import { SERVER_VERSION } from './version.js';
 const DEFAULT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
-// Exit on fatal errors to prevent silent zombie processes (issue #5)
+// Exit on fatal errors to prevent silent zombie processes (issue #5).
+// We log an explicit whitelist of fields rather than the raw error object
+// to avoid ever echoing sensitive SDK internals (request bodies, auth
+// headers) in a future version. Defense-in-depth against a changed
+// APIError.toString() in openai-node.
+function logFatal(kind, err) {
+    const e = err;
+    logger.error('fatal', {
+        kind,
+        name: e?.name ?? 'unknown',
+        msg: e?.message ?? String(err),
+        // Stack traces are developer-only — trim to avoid unbounded log lines.
+        stack: e?.stack?.split('\n').slice(0, 10).join('\n'),
+    });
+}
 process.on('uncaughtException', (err) => {
-    console.error('[Fatal]', err);
+    logFatal('uncaughtException', err);
     process.exit(1);
 });
 process.on('unhandledRejection', (err) => {
-    console.error('[Fatal]', err);
+    logFatal('unhandledRejection', err);
     process.exit(1);
 });
 const apiKey = process.env.OPENROUTER_API_KEY;
@@ -21,8 +37,8 @@ if (!apiKey) {
     process.exit(1);
 }
 const defaultModel = process.env.OPENROUTER_DEFAULT_MODEL || process.env.DEFAULT_MODEL || DEFAULT_MODEL;
-const server = new Server({ name: 'openrouter-multimodal-server', version: '4.0.1' }, { capabilities: { tools: {} } });
-server.onerror = (error) => console.error('[MCP Error]', error);
+const server = new Server({ name: 'openrouter-multimodal-server', version: SERVER_VERSION }, { capabilities: { tools: {} } });
+server.onerror = (error) => logFatal('mcpError', error);
 new ToolHandlers(server, apiKey, defaultModel);
 process.on('SIGINT', async () => {
     await server.close();

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

@@ -12,10 +12,23 @@ export declare class ModelCache {
     private static instance;
     private models;
     private fetchedAt;
+    /**
+     * Separate from `fetchedAt`: set whenever we successfully CALL the
+     * fetcher (even if the response happens to be empty). Used by
+     * `isValid()` so a successful-but-empty fetch still counts as "fresh"
+     * and we don't hot-loop re-fetching the upstream.
+     */
+    private populatedAt;
     private inflight;
     static getInstance(): ModelCache;
     isValid(): boolean;
     setModels(models: OpenRouterModelRecord[]): void;
+    /**
+     * Force the cache back into an uninitialized state. Used by tests that
+     * need to assert `ensureFresh()` actually calls the fetcher. Also useful
+     * for ops (`health_check --reset`) if we ever expose such a knob.
+     */
+    reset(): void;
     /**
      * Populate the cache using `fetcher` if stale, coalescing concurrent callers
      * so only one request hits the upstream API per stale window. Callers that
@@ -23,6 +36,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 +49,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

@@ -10,16 +10,36 @@ export class ModelCache {
     static instance;
     models = {};
     fetchedAt = 0;
+    /**
+     * Separate from `fetchedAt`: set whenever we successfully CALL the
+     * fetcher (even if the response happens to be empty). Used by
+     * `isValid()` so a successful-but-empty fetch still counts as "fresh"
+     * and we don't hot-loop re-fetching the upstream.
+     */
+    populatedAt = 0;
     inflight = null;
     static getInstance() {
         return (ModelCache.instance ??= new ModelCache());
     }
     isValid() {
-        return Object.keys(this.models).length > 0 && Date.now() - this.fetchedAt < getCacheTtlMs();
+        const fresh = Date.now() - this.populatedAt < getCacheTtlMs();
+        return this.populatedAt > 0 && fresh;
     }
     setModels(models) {
         this.models = Object.fromEntries(models.map((m) => [m.id, m]));
         this.fetchedAt = Date.now();
+        this.populatedAt = this.fetchedAt;
+    }
+    /**
+     * Force the cache back into an uninitialized state. Used by tests that
+     * need to assert `ensureFresh()` actually calls the fetcher. Also useful
+     * for ops (`health_check --reset`) if we ever expose such a knob.
+     */
+    reset() {
+        this.models = {};
+        this.fetchedAt = 0;
+        this.populatedAt = 0;
+        this.inflight = null;
     }
     /**
      * Populate the cache using `fetcher` if stale, coalescing concurrent callers
@@ -45,6 +65,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 +94,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 }),
     };
 }