@stabgan/openrouter-mcp-multimodal 4.6.1 → 4.6.2

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

@@ -4,11 +4,6 @@ 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: {

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

@@ -4,12 +4,6 @@ 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: {

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

@@ -29,9 +29,6 @@ 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 },
@@ -69,11 +66,7 @@ export async function handleAnalyzeImage(request, openai, defaultModel) {
         });
     }
     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).
+    // Vision output may reflect untrusted image content — flag for downstream agents.
     const extra = {
         server_version: SERVER_VERSION,
         content_is_untrusted: true,

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

@@ -4,11 +4,6 @@ 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: {

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

@@ -7,11 +7,6 @@ import { classifyUpstreamError } from './openrouter-errors.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
- * `OPENROUTER_DEFAULT_VIDEO_MODEL` or per-call `model`.
- */
 const FALLBACK_DEFAULT_MODEL = 'google/gemini-2.5-flash';
 export async function handleAnalyzeVideo(request, openai, defaultModel) {
     const args = request.params.arguments ?? { video_path: '' };
@@ -41,8 +36,6 @@ 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}` },
     };

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

@@ -1,21 +1,25 @@
 import OpenAI from 'openai';
-import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
-import { type ProviderRoutingOptions } from './provider-routing.js';
-import { type CacheOptions } from './cache.js';
-export interface StartChatCompletionRequest extends CacheOptions {
-    messages: ChatCompletionMessageParam[];
-    model?: string;
-    temperature?: number;
-    max_tokens?: number;
-    provider?: ProviderRoutingOptions;
-    include_reasoning?: boolean;
-    online?: boolean;
-    web_max_results?: number;
-}
+import { ErrorCode } from '../errors.js';
+import { type ChatToolRequest } from './chat-request.js';
+export type StartChatCompletionRequest = ChatToolRequest;
 export interface GetChatCompletionStatusRequest {
     job_id: string;
 }
 export type AsyncJobStatus = 'queued' | 'running' | 'completed' | 'failed';
+export interface AsyncJob {
+    id: string;
+    status: AsyncJobStatus;
+    createdAt: string;
+    model: string;
+    result?: {
+        text: string;
+        meta: Record<string, unknown>;
+    };
+    error?: string;
+    error_code?: ErrorCode;
+}
+/** Load a persisted job from disk (exported for tests). */
+export declare function loadJobFromDisk(jobId: string): Promise<AsyncJob | null>;
 export declare function handleStartChatCompletion(request: {
     params: {
         arguments: StartChatCompletionRequest;

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

@@ -1,29 +1,12 @@
-/**
- * Async chat completions — resumable workflow for long-running requests.
- *
- * Problem: Remote MCP bridges (Cowork, etc.) kill tool calls after ~60s.
- * Reasoning models can take much longer. Unlike video, `chat_completion`
- * currently has no background job mechanism.
- *
- * Solution: Two tools that mirror the video pattern:
- *  - `start_chat_completion` — fires off the request in the background,
- *    returns a `job_id` immediately.
- *  - `get_chat_completion_status` — returns queued/running/completed/failed,
- *    with the final response on completion.
- *
- * Job state is held in memory (survives within a single MCP session).
- * Optionally persisted to OPENROUTER_OUTPUT_DIR/openrouter-jobs/ for
- * crash recovery.
- */
-import { promises as fs } from 'fs';
+/** Async chat completions — in-memory jobs, optionally persisted under OPENROUTER_OUTPUT_DIR/openrouter-jobs/. */
+import { promises as fs } from 'node:fs';
 import path from 'node:path';
 import { ErrorCode, toolError } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { extractCompletionText, buildCompletionMeta } from './completion-utils.js';
-import { readProviderDefaults, mergeProviderOptions, buildProviderBody, resolveMaxTokens, } from './provider-routing.js';
-import { buildCacheHeaders } from './cache.js';
-// ─── Job Store ───────────────────────────────────────────────────────────────
+import { classifyUpstreamError } from './openrouter-errors.js';
+import { DEFAULT_CHAT_MODEL, buildChatCompletionBody, buildChatCompletionRequestOpts, asOpenAIChatBody, readIncludeReasoningDefault, } from './chat-request.js';
 const jobs = new Map();
 let jobCounter = 0;
 function generateJobId() {
@@ -56,11 +39,29 @@ async function persistJob(job) {
         });
     }
 }
-// ─── Handlers ────────────────────────────────────────────────────────────────
-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';
+/** Load a persisted job from disk (exported for tests). */
+export async function loadJobFromDisk(jobId) {
+    const dir = getJobsDir();
+    if (!dir)
+        return null;
+    try {
+        const raw = await fs.readFile(path.join(dir, jobId, 'status.json'), 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveJob(jobId) {
+    const inMemory = jobs.get(jobId);
+    if (inMemory)
+        return inMemory;
+    const fromDisk = await loadJobFromDisk(jobId);
+    if (fromDisk) {
+        jobs.set(jobId, fromDisk);
+        return fromDisk;
+    }
+    return undefined;
 }
 export async function handleStartChatCompletion(request, openai, defaultModel) {
     const args = request.params.arguments ?? { messages: [] };
@@ -68,9 +69,8 @@ export async function handleStartChatCompletion(request, openai, defaultModel) {
     if (!messages?.length) {
         return toolError(ErrorCode.INVALID_INPUT, 'Messages array cannot be empty.');
     }
-    const effectiveModel = model || defaultModel || DEFAULT_MODEL;
+    const effectiveModel = model || defaultModel || DEFAULT_CHAT_MODEL;
     const jobId = generateJobId();
-    // Create the job immediately
     const job = {
         id: jobId,
         status: 'running',
@@ -83,8 +83,7 @@ export async function handleStartChatCompletion(request, openai, defaultModel) {
         model: effectiveModel,
         message_count: messages.length,
     });
-    // Fire and forget — the completion runs in the background
-    runCompletionInBackground(job, openai, {
+    void runCompletionInBackground(job, openai, {
         messages,
         model: effectiveModel,
         temperature,
@@ -97,7 +96,6 @@ export async function handleStartChatCompletion(request, openai, defaultModel) {
         cache_ttl,
         cache_clear,
     });
-    // Return immediately with the job ID
     return {
         content: [
             {
@@ -114,36 +112,11 @@ export async function handleStartChatCompletion(request, openai, defaultModel) {
     };
 }
 async function runCompletionInBackground(job, openai, opts) {
-    const providerOptions = mergeProviderOptions(readProviderDefaults(), opts.provider);
-    const providerBody = buildProviderBody(providerOptions);
-    const effectiveMaxTokens = resolveMaxTokens(opts.max_tokens);
     const wantsReasoning = opts.include_reasoning ?? readIncludeReasoningDefault();
-    const body = {
-        model: opts.model,
-        messages: opts.messages,
-        temperature: opts.temperature ?? 1,
-    };
-    if (typeof effectiveMaxTokens === 'number')
-        body.max_tokens = effectiveMaxTokens;
-    if (providerBody)
-        body.provider = providerBody;
-    if (wantsReasoning)
-        body.include_reasoning = true;
-    if (opts.online) {
-        const plugin = { id: 'web' };
-        if (typeof opts.web_max_results === 'number' && opts.web_max_results > 0) {
-            plugin.max_results = opts.web_max_results;
-        }
-        body.plugins = [plugin];
-    }
-    const headers = buildCacheHeaders({
-        cache: opts.cache,
-        cache_ttl: opts.cache_ttl,
-        cache_clear: opts.cache_clear,
-    });
-    const requestOpts = Object.keys(headers).length > 0 ? { headers } : undefined;
+    const body = buildChatCompletionBody(opts);
+    const requestOpts = buildChatCompletionRequestOpts(opts);
     try {
-        const completion = (await openai.chat.completions.create(body, requestOpts));
+        const completion = (await openai.chat.completions.create(asOpenAIChatBody(body), requestOpts));
         const extracted = extractCompletionText(completion);
         if (!extracted.text) {
             job.status = 'failed';
@@ -162,8 +135,10 @@ async function runCompletionInBackground(job, openai, opts) {
     }
     catch (err) {
         job.status = 'failed';
-        job.error = err instanceof Error ? err.message : String(err);
-        logger.warn('async_chat.failed', { job_id: job.id, error: job.error });
+        const classified = classifyUpstreamError(err);
+        job.error = classified.content[0]?.text ?? 'Job failed.';
+        job.error_code = classified._meta.code;
+        logger.warn('async_chat.failed', { job_id: job.id, error: job.error, code: job.error_code });
     }
     await persistJob(job);
 }
@@ -173,9 +148,12 @@ export async function handleGetChatCompletionStatus(request) {
     if (!jobId) {
         return toolError(ErrorCode.INVALID_INPUT, 'job_id is required.');
     }
-    const job = jobs.get(jobId);
+    const job = await resolveJob(jobId);
     if (!job) {
-        return toolError(ErrorCode.INVALID_INPUT, `No job found with id "${jobId}". Jobs are stored in memory for the current session only.`);
+        const hint = getJobsDir()
+            ? ' Jobs persist under OPENROUTER_OUTPUT_DIR/openrouter-jobs/ when that env var is set.'
+            : ' Jobs are stored in memory for the current session only.';
+        return toolError(ErrorCode.INVALID_INPUT, `No job found with id "${jobId}".${hint}`);
     }
     if (job.status === 'completed' && job.result) {
         return {
@@ -191,13 +169,12 @@ export async function handleGetChatCompletionStatus(request) {
         };
     }
     if (job.status === 'failed') {
-        return toolError(ErrorCode.JOB_FAILED, job.error || 'Job failed.', {
+        return toolError(job.error_code ?? ErrorCode.JOB_FAILED, job.error || 'Job failed.', {
             job_id: jobId,
             model: job.model,
             created_at: job.createdAt,
         });
     }
-    // Still running
     return {
         content: [
             {

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

@@ -12,8 +12,5 @@ export interface AudioData {
     data: string;
     format: AudioFormat;
 }
-/**
- * Prepare audio from any source (data URL, HTTP URL, local file) as base64 + format.
- * OpenRouter requires audio to be base64-encoded; direct URLs are NOT supported.
- */
+/** Prepare audio from data URL, HTTP URL, or sandboxed local file. */
 export declare function prepareAudioData(source: string): Promise<AudioData>;

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

@@ -1,9 +1,6 @@
-/**
- * Audio format detection, base64 encoding, and fetch utilities.
- * Network/security logic is delegated to fetch-utils.ts (zero duplication).
- */
-import path from 'path';
-import { promises as fs } from 'fs';
+/** Audio format detection and fetch utilities. */
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
 import { readEnvInt, fetchHttpResource, parseBase64DataUrl } from './fetch-utils.js';
 import { resolveSafeInputPath } from './path-safety.js';
 // Re-export for tests
@@ -83,12 +80,8 @@ function formatFromContentType(ct) {
         return undefined;
     return mimeSubtypeToFormat(mime.slice(6));
 }
-/**
- * Prepare audio from any source (data URL, HTTP URL, local file) as base64 + format.
- * OpenRouter requires audio to be base64-encoded; direct URLs are NOT supported.
- */
+/** Prepare audio from data URL, HTTP URL, or sandboxed local file. */
 export async function prepareAudioData(source) {
-    // --- data URL ---
     if (source.startsWith('data:')) {
         const parsed = parseBase64DataUrl(source);
         if (!parsed)
@@ -102,14 +95,12 @@ export async function prepareAudioData(source) {
             throw new Error('Data URL too large');
         return { data: parsed.base64, format };
     }
-    // --- HTTP(S) URL ---
     if (source.startsWith('http://') || source.startsWith('https://')) {
         const { buffer, contentType } = await fetchHttpResource(source, {
             timeoutMs: getFetchTimeoutMs(),
             maxBytes: getMaxDownloadBytes(),
             maxRedirects: getMaxRedirects(),
         });
-        // Try URL path extension first, fall back to Content-Type header
         const urlPath = new URL(source).pathname;
         const format = getAudioFormat(urlPath) ?? formatFromContentType(contentType);
         if (!format) {
@@ -117,7 +108,6 @@ export async function prepareAudioData(source) {
         }
         return { data: buffer.toString('base64'), format };
     }
-    // --- local file ---
     const safe = await resolveSafeInputPath(source);
     const format = getAudioFormat(safe);
     if (!format) {

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

@@ -1,15 +1,4 @@
-/**
- * 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.
- */
+/** OpenRouter response caching via X-OpenRouter-Cache headers. */
 export interface CacheOptions {
     cache?: boolean;
     cache_ttl?: string;
@@ -17,12 +6,7 @@ export interface CacheOptions {
 }
 /** 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.
- */
+/** Build X-OpenRouter-Cache headers for chat/analyze requests. */
 export declare function buildCacheHeaders(opts: CacheOptions | undefined): Record<string, string>;
 /** Extract cache metadata from response headers, null when not present. */
 export interface CacheMeta {

package/dist/tool-handlers/cache.js

@@ -1,30 +1,12 @@
-/**
- * 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.
- */
+/** Build X-OpenRouter-Cache headers for chat/analyze requests. */
 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';

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

@@ -1,34 +1,6 @@
 import OpenAI from 'openai';
-import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
-import { type ProviderRoutingOptions } from './provider-routing.js';
-import { type CacheOptions } from './cache.js';
-export interface ChatCompletionToolRequest extends CacheOptions {
-    model?: string;
-    messages: ChatCompletionMessageParam[];
-    temperature?: number;
-    max_tokens?: number;
-    /**
-     * OpenRouter provider routing overrides. Merges on top of the
-     * `OPENROUTER_PROVIDER_*` env-var defaults. See
-     * 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;
-}
+import { type ChatToolRequest } from './chat-request.js';
+export type ChatCompletionToolRequest = ChatToolRequest;
 export declare function handleChatCompletion(request: {
     params: {
         arguments: ChatCompletionToolRequest;

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

@@ -2,51 +2,31 @@ import { ErrorCode, toolError } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { classifyUpstreamError } from './openrouter-errors.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 { 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';
-}
+import { DEFAULT_CHAT_MODEL, buildChatCompletionBody, buildChatCompletionRequestOpts, asOpenAIChatBody, readIncludeReasoningDefault, } from './chat-request.js';
 export async function handleChatCompletion(request, openai, defaultModel) {
     const args = request.params.arguments ?? { messages: [] };
     const { messages, model, temperature, max_tokens, provider, include_reasoning, online, web_max_results, cache, cache_ttl, cache_clear, } = args;
     if (!messages?.length) {
         return toolError(ErrorCode.INVALID_INPUT, 'Messages array cannot be empty.');
     }
-    const providerOptions = mergeProviderOptions(readProviderDefaults(), provider);
-    const providerBody = buildProviderBody(providerOptions);
-    const effectiveMaxTokens = resolveMaxTokens(max_tokens);
     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,
+    const body = buildChatCompletionBody({
         messages,
-        temperature: temperature ?? 1,
-    };
-    if (typeof effectiveMaxTokens === 'number')
-        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;
+        model: model || defaultModel || DEFAULT_CHAT_MODEL,
+        temperature,
+        max_tokens,
+        provider,
+        include_reasoning,
+        online,
+        web_max_results,
+    });
+    const requestOpts = buildChatCompletionRequestOpts({ cache, cache_ttl, cache_clear });
     let completion;
     let responseHeaders;
     try {
-        const call = openai.chat.completions.create(body, requestOpts);
+        const call = openai.chat.completions.create(asOpenAIChatBody(body), requestOpts);
         const { data, response } = await awaitCompletionWithHeaders(call);
         completion = data;
         responseHeaders = response?.headers;

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

@@ -0,0 +1,25 @@
+import type OpenAI from 'openai';
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
+import { type ProviderRoutingOptions } from './provider-routing.js';
+import { type CacheOptions } from './cache.js';
+export declare const DEFAULT_CHAT_MODEL = "nvidia/nemotron-nano-12b-v2-vl:free";
+/** Shared request shape for sync and async chat completion tools. */
+export interface ChatToolRequest extends CacheOptions {
+    model?: string;
+    messages: ChatCompletionMessageParam[];
+    temperature?: number;
+    max_tokens?: number;
+    provider?: ProviderRoutingOptions;
+    include_reasoning?: boolean;
+    online?: boolean;
+    web_max_results?: number;
+}
+export declare function readIncludeReasoningDefault(): boolean;
+export declare function buildChatCompletionBody(input: ChatToolRequest & {
+    model: string;
+}): Record<string, unknown>;
+export declare function buildChatCompletionRequestOpts(cache: CacheOptions): {
+    headers: Record<string, string>;
+} | undefined;
+export type OpenAIChatCreateBody = Parameters<OpenAI['chat']['completions']['create']>[0];
+export declare function asOpenAIChatBody(body: Record<string, unknown>): OpenAIChatCreateBody;

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

@@ -0,0 +1,38 @@
+import { readProviderDefaults, mergeProviderOptions, buildProviderBody, resolveMaxTokens, } from './provider-routing.js';
+import { buildCacheHeaders } from './cache.js';
+export const DEFAULT_CHAT_MODEL = 'nvidia/nemotron-nano-12b-v2-vl:free';
+export function readIncludeReasoningDefault() {
+    const raw = (process.env.OPENROUTER_INCLUDE_REASONING ?? '').trim().toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
+export function buildChatCompletionBody(input) {
+    const providerBody = buildProviderBody(mergeProviderOptions(readProviderDefaults(), input.provider));
+    const effectiveMaxTokens = resolveMaxTokens(input.max_tokens);
+    const wantsReasoning = input.include_reasoning ?? readIncludeReasoningDefault();
+    const body = {
+        model: input.model,
+        messages: input.messages,
+        temperature: input.temperature ?? 1,
+    };
+    if (typeof effectiveMaxTokens === 'number')
+        body.max_tokens = effectiveMaxTokens;
+    if (providerBody)
+        body.provider = providerBody;
+    if (wantsReasoning)
+        body.include_reasoning = true;
+    if (input.online) {
+        const plugin = { id: 'web' };
+        if (typeof input.web_max_results === 'number' && input.web_max_results > 0) {
+            plugin.max_results = input.web_max_results;
+        }
+        body.plugins = [plugin];
+    }
+    return body;
+}
+export function buildChatCompletionRequestOpts(cache) {
+    const headers = buildCacheHeaders(cache);
+    return Object.keys(headers).length > 0 ? { headers } : undefined;
+}
+export function asOpenAIChatBody(body) {
+    return body;
+}

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

@@ -1,11 +1,5 @@
 /**
- * Shared helpers for tools that call `openai.chat.completions.create` and
- * return the assistant's message as text. Handles:
- *   - plain string content (the common case)
- *   - multimodal array content (concatenate text parts)
- *   - reasoning-only responses (`content: null` + `reasoning`/`reasoning_details`)
- *   - `finish_reason === 'length'` — warn the caller so they know to raise
- *     `max_tokens` instead of silently getting nothing back.
+ * Helpers for chat completion responses — text extraction, reasoning, finish reasons.
  */
 import type { ChatCompletion } from 'openai/resources/chat/completions.js';
 import { type ToolErrorResult } from '../errors.js';
@@ -14,18 +8,7 @@ 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'];
 }

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

@@ -16,8 +16,6 @@ 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) {