@stabgan/openrouter-mcp-multimodal 4.7.0 → 5.0.0

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

@@ -3,37 +3,78 @@ 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
 export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
 const DEFAULT_FETCH_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_DOWNLOAD_BYTES = 25 * 1024 * 1024;
 const DEFAULT_MAX_REDIRECTS = 8;
-const DEFAULT_MAX_DATA_URL_BYTES = 20 * 1024 * 1024;
 function getFetchTimeoutMs() {
     return readEnvInt('OPENROUTER_AUDIO_FETCH_TIMEOUT_MS', DEFAULT_FETCH_TIMEOUT_MS, 1000);
 }
-function getMaxDownloadBytes() {
-    return readEnvInt('OPENROUTER_AUDIO_MAX_DOWNLOAD_BYTES', DEFAULT_MAX_DOWNLOAD_BYTES, 1024);
+/** Shared ceiling for speech_to_text local, HTTP, and data-URL inputs. */
+export function getMaxAudioInputBytes() {
+    return readEnvInt('OPENROUTER_AUDIO_MAX_DOWNLOAD_BYTES', DEFAULT_MAX_DOWNLOAD_BYTES, 1);
 }
 function getMaxRedirects() {
     return readEnvInt('OPENROUTER_AUDIO_MAX_REDIRECTS', DEFAULT_MAX_REDIRECTS, 0);
 }
-function getMaxDataUrlBytes() {
-    return readEnvInt('OPENROUTER_AUDIO_MAX_DATA_URL_BYTES', DEFAULT_MAX_DATA_URL_BYTES, 1024);
-}
-/** File-extension formats (matchable by .ext) */
 const FILE_AUDIO_FORMATS = ['wav', 'mp3', 'aiff', 'aac', 'ogg', 'flac', 'm4a'];
-/** API-only formats (no real file extension) */
 const API_AUDIO_FORMATS = ['pcm16', 'pcm24'];
 export const SUPPORTED_AUDIO_FORMATS = [...FILE_AUDIO_FORMATS, ...API_AUDIO_FORMATS];
-/** Get audio format from file extension. Returns undefined for non-audio or API-only formats. */
+export const STT_FILE_EXTENSIONS = [
+    'mp3',
+    'mp4',
+    'm4a',
+    'wav',
+    'flac',
+    'ogg',
+    'oga',
+    'webm',
+    'opus',
+];
+/**
+ * Detect audio container format from magic bytes. MP3 detection is strict:
+ * ID3 tags or frame sync with valid MPEG header fields.
+ */
+export function detectAudioFormat(data) {
+    if (data.length >= 3 && data[0] === 0x49 && data[1] === 0x44 && data[2] === 0x33) {
+        return { ext: 'mp3', mimeType: 'audio/mpeg' };
+    }
+    if (data.length >= 4 && data[0] === 0xff && (data[1] & 0xe0) === 0xe0) {
+        const b1 = data[1];
+        const b2 = data[2];
+        const versionBits = (b1 >> 3) & 0x03;
+        const layerBits = (b1 >> 1) & 0x03;
+        const bitrateIndex = (b2 >> 4) & 0x0f;
+        const sampleRateIndex = (b2 >> 2) & 0x03;
+        if (versionBits !== 0x01 &&
+            layerBits !== 0x00 &&
+            bitrateIndex !== 0x0f &&
+            sampleRateIndex !== 0x03) {
+            return { ext: 'mp3', mimeType: 'audio/mpeg' };
+        }
+    }
+    if (data.length >= 12) {
+        const riff = data.subarray(0, 4).toString('ascii');
+        const wave = data.subarray(8, 12).toString('ascii');
+        if (riff === 'RIFF' && wave === 'WAVE') {
+            return { ext: 'wav', mimeType: 'audio/wav' };
+        }
+    }
+    if (data.length >= 4) {
+        const magic = data.subarray(0, 4).toString('ascii');
+        if (magic === 'fLaC')
+            return { ext: 'flac', mimeType: 'audio/flac' };
+        if (magic === 'OggS')
+            return { ext: 'ogg', mimeType: 'audio/ogg' };
+    }
+    return { ext: 'pcm', mimeType: 'audio/pcm' };
+}
 export function getAudioFormat(filePath) {
     const ext = path.extname(filePath).toLowerCase().slice(1);
     return FILE_AUDIO_FORMATS.includes(ext)
         ? ext
         : undefined;
 }
-/** Get MIME type for an audio format. */
 export function getAudioMimeType(format) {
     const map = {
         wav: 'audio/wav',
@@ -48,7 +89,6 @@ export function getAudioMimeType(format) {
     };
     return map[format] || 'audio/wav';
 }
-/** Map a MIME subtype (e.g. "mpeg", "wave") to an AudioFormat. */
 function mimeSubtypeToFormat(subtype) {
     const aliasMap = {
         mpeg: 'mp3',
@@ -71,7 +111,6 @@ function mimeSubtypeToFormat(subtype) {
             ? lower
             : undefined));
 }
-/** Derive AudioFormat from a Content-Type header value. */
 function formatFromContentType(ct) {
     if (!ct)
         return undefined;
@@ -80,7 +119,6 @@ function formatFromContentType(ct) {
         return undefined;
     return mimeSubtypeToFormat(mime.slice(6));
 }
-/** Prepare audio from data URL, HTTP URL, or sandboxed local file. */
 export async function prepareAudioData(source) {
     if (source.startsWith('data:')) {
         const parsed = parseBase64DataUrl(source);
@@ -91,14 +129,14 @@ export async function prepareAudioData(source) {
             throw new Error(`Unsupported audio format from MIME: ${parsed.mediaType}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
         }
         const approxBytes = Math.ceil((parsed.base64.length * 3) / 4);
-        if (approxBytes > getMaxDataUrlBytes())
+        if (approxBytes > getMaxAudioInputBytes())
             throw new Error('Data URL too large');
         return { data: parsed.base64, format };
     }
     if (source.startsWith('http://') || source.startsWith('https://')) {
         const { buffer, contentType } = await fetchHttpResource(source, {
             timeoutMs: getFetchTimeoutMs(),
-            maxBytes: getMaxDownloadBytes(),
+            maxBytes: getMaxAudioInputBytes(),
             maxRedirects: getMaxRedirects(),
         });
         const urlPath = new URL(source).pathname;
@@ -113,6 +151,122 @@ export async function prepareAudioData(source) {
     if (!format) {
         throw new Error(`Unsupported audio format for file: ${source}. Supported: ${SUPPORTED_AUDIO_FORMATS.join(', ')}`);
     }
+    const { size } = await fs.stat(safe);
+    assertWithinAudioInputLimit(size, 'Audio file');
     const buffer = await fs.readFile(safe);
     return { data: buffer.toString('base64'), format };
 }
+/** Map a speech_to_text file extension to the upstream format slug. */
+export function sttFormatFromExtension(ext) {
+    const normalized = ext.toLowerCase().replace(/^\./, '');
+    switch (normalized) {
+        case 'mp3':
+            return 'mp3';
+        case 'mp4':
+        case 'm4a':
+            return 'mp4';
+        case 'wav':
+            return 'wav';
+        case 'flac':
+            return 'flac';
+        case 'ogg':
+        case 'oga':
+            return 'ogg';
+        case 'webm':
+            return 'webm';
+        case 'opus':
+            return 'opus';
+        default:
+            throw new Error(`Unsupported audio format for file extension '.${normalized}'. Supported: ${STT_FILE_EXTENSIONS.join(', ')}.`);
+    }
+}
+function sttFormatFromMimeSubtype(subtype) {
+    const lower = subtype.toLowerCase();
+    switch (lower) {
+        case 'mpeg':
+        case 'mp3':
+            return 'mp3';
+        case 'wav':
+        case 'wave':
+            return 'wav';
+        case 'flac':
+            return 'flac';
+        case 'ogg':
+            return 'ogg';
+        case 'webm':
+            return 'webm';
+        case 'opus':
+            return 'opus';
+        case 'mp4':
+        case 'm4a':
+        case 'x-m4a':
+            return 'mp4';
+        default:
+            if (STT_FILE_EXTENSIONS.includes(lower)) {
+                return sttFormatFromExtension(lower);
+            }
+            return undefined;
+    }
+}
+function assertWithinAudioInputLimit(byteCount, label) {
+    const maxBytes = getMaxAudioInputBytes();
+    if (byteCount > maxBytes) {
+        throw new Error(`${label} too large (${byteCount} bytes, max ${maxBytes})`);
+    }
+}
+/** Resolve speech_to_text audio from data URL, HTTP URL, or sandboxed local file. */
+export async function resolveSpeechToTextAudio(audioPath) {
+    const trimmed = audioPath.trim();
+    if (!trimmed)
+        throw new Error('audio_path is empty');
+    if (trimmed.startsWith('data:')) {
+        const parsed = parseBase64DataUrl(trimmed);
+        if (!parsed || !parsed.mediaType.startsWith('audio/')) {
+            throw new Error('Invalid audio data URL format');
+        }
+        const approxBytes = Math.ceil((parsed.base64.length * 3) / 4);
+        assertWithinAudioInputLimit(approxBytes, 'Data URL');
+        const format = sttFormatFromMimeSubtype(parsed.mediaType.split('/')[1] ?? '');
+        if (!format) {
+            throw new Error(`Unsupported audio format from MIME: ${parsed.mediaType}. Supported: ${STT_FILE_EXTENSIONS.join(', ')}.`);
+        }
+        return { data: parsed.base64, format };
+    }
+    if (/^https?:\/\//i.test(trimmed)) {
+        const { buffer, contentType } = await fetchHttpResource(trimmed, {
+            timeoutMs: getFetchTimeoutMs(),
+            maxBytes: getMaxAudioInputBytes(),
+            maxRedirects: getMaxRedirects(),
+        });
+        assertWithinAudioInputLimit(buffer.length, 'Audio download');
+        const ext = path.extname(new URL(trimmed).pathname);
+        let format;
+        if (ext) {
+            try {
+                format = sttFormatFromExtension(ext);
+            }
+            catch {
+                format = undefined;
+            }
+        }
+        format =
+            format ??
+                (contentType
+                    ? sttFormatFromMimeSubtype(contentType
+                        .split(';')[0]
+                        .trim()
+                        .toLowerCase()
+                        .replace(/^audio\//, ''))
+                    : undefined);
+        if (!format) {
+            throw new Error(`Unsupported audio format from URL: ${trimmed}. Supported: ${STT_FILE_EXTENSIONS.join(', ')}.`);
+        }
+        return { data: buffer.toString('base64'), format };
+    }
+    const abs = await resolveSafeInputPath(trimmed);
+    const { size } = await fs.stat(abs);
+    assertWithinAudioInputLimit(size, 'Audio file');
+    const buf = await fs.readFile(abs);
+    const format = sttFormatFromExtension(path.extname(abs));
+    return { data: buf.toString('base64'), format };
+}

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

@@ -1,14 +1,14 @@
 /** OpenRouter response caching via X-OpenRouter-Cache headers. */
+import { type ToolErrorResult } from '../errors.js';
 export interface CacheOptions {
     cache?: boolean;
     cache_ttl?: string;
     cache_clear?: boolean;
 }
-/** Parse the env-default and return `true` when caching should be on by default. */
 export declare function readCacheDefault(): boolean;
-/** Build X-OpenRouter-Cache headers for chat/analyze requests. */
+export declare function resolveCacheTtl(cacheTtl: string): string | ToolErrorResult;
+export declare function validateCacheOptions(opts: CacheOptions | undefined): ToolErrorResult | null;
 export declare function buildCacheHeaders(opts: CacheOptions | undefined): Record<string, string>;
-/** Extract cache metadata from response headers, null when not present. */
 export interface CacheMeta {
     status: 'HIT' | 'MISS' | string;
     age?: number;

package/dist/tool-handlers/cache.js

@@ -1,17 +1,69 @@
-/** Parse the env-default and return `true` when caching should be on by default. */
+/** OpenRouter response caching via X-OpenRouter-Cache headers. */
+import { ErrorCode, toolError } from '../errors.js';
+const MIN_CACHE_TTL_SECONDS = 1;
+const MAX_CACHE_TTL_SECONDS = 86_400;
+const INTEGER_TTL_RE = /^\d+$/;
+const DURATION_TTL_RE = /^(\d+)([smh])$/i;
+const CACHE_TTL_INVALID_MSG = `cache_ttl must be an integer seconds value (${MIN_CACHE_TTL_SECONDS}–${MAX_CACHE_TTL_SECONDS}) ` +
+    'or a duration string like "30s", "5m", or "1h".';
 export function readCacheDefault() {
     const raw = (process.env.OPENROUTER_CACHE_RESPONSES ?? '').trim().toLowerCase();
     return raw === '1' || raw === 'true' || raw === 'yes';
 }
-/** Build X-OpenRouter-Cache headers for chat/analyze requests. */
+export function resolveCacheTtl(cacheTtl) {
+    const trimmed = cacheTtl.trim();
+    if (!trimmed) {
+        return toolError(ErrorCode.INVALID_INPUT, CACHE_TTL_INVALID_MSG);
+    }
+    let seconds;
+    const durationMatch = DURATION_TTL_RE.exec(trimmed);
+    if (durationMatch) {
+        const value = Number.parseInt(durationMatch[1], 10);
+        const unit = durationMatch[2].toLowerCase();
+        switch (unit) {
+            case 's':
+                seconds = value;
+                break;
+            case 'm':
+                seconds = value * 60;
+                break;
+            case 'h':
+                seconds = value * 3600;
+                break;
+            default: {
+                const _exhaustive = unit;
+                return toolError(ErrorCode.INVALID_INPUT, CACHE_TTL_INVALID_MSG);
+            }
+        }
+    }
+    else if (INTEGER_TTL_RE.test(trimmed)) {
+        seconds = Number.parseInt(trimmed, 10);
+    }
+    else {
+        return toolError(ErrorCode.INVALID_INPUT, CACHE_TTL_INVALID_MSG);
+    }
+    if (seconds < MIN_CACHE_TTL_SECONDS || seconds > MAX_CACHE_TTL_SECONDS) {
+        return toolError(ErrorCode.INVALID_INPUT, `cache_ttl must be between ${MIN_CACHE_TTL_SECONDS} and ${MAX_CACHE_TTL_SECONDS} seconds (inclusive).`);
+    }
+    return String(seconds);
+}
+export function validateCacheOptions(opts) {
+    if (!opts?.cache_ttl)
+        return null;
+    const resolved = resolveCacheTtl(opts.cache_ttl);
+    return typeof resolved === 'string' ? null : resolved;
+}
 export function buildCacheHeaders(opts) {
     const headers = {};
     const defaultOn = readCacheDefault();
     const enabled = opts?.cache ?? defaultOn;
     if (enabled)
         headers['X-OpenRouter-Cache'] = 'true';
-    if (opts?.cache_ttl)
-        headers['X-OpenRouter-Cache-TTL'] = opts.cache_ttl;
+    if (opts?.cache_ttl) {
+        const resolved = resolveCacheTtl(opts.cache_ttl);
+        if (typeof resolved === 'string')
+            headers['X-OpenRouter-Cache-TTL'] = resolved;
+    }
     if (opts?.cache_clear)
         headers['X-OpenRouter-Cache-Clear'] = 'true';
     return headers;

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

@@ -1,16 +1,22 @@
 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 { extractCacheMeta } from './cache.js';
+import { extractCompletionText, detectReasoningCutoff, buildCompletionMeta, capResultText, } from './completion-utils.js';
+import { extractCacheMeta, validateCacheOptions } from './cache.js';
 import { awaitCompletionWithHeaders } from './openai-withresponse.js';
-import { DEFAULT_CHAT_MODEL, buildChatCompletionBody, buildChatCompletionRequestOpts, asOpenAIChatBody, readIncludeReasoningDefault, } from './chat-request.js';
+import { DEFAULT_CHAT_MODEL, buildChatCompletionBody, buildChatCompletionRequestOpts, asOpenAIChatBody, readIncludeReasoningDefault, validateChatMessages, validateMaxTokens, } 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 messagesError = validateChatMessages(messages);
+    if (messagesError)
+        return messagesError;
+    const cacheError = validateCacheOptions({ cache, cache_ttl, cache_clear });
+    if (cacheError)
+        return cacheError;
+    const maxTokensError = validateMaxTokens(max_tokens);
+    if (maxTokensError)
+        return maxTokensError;
     const wantsReasoning = include_reasoning ?? readIncludeReasoningDefault();
     const body = buildChatCompletionBody({
         messages,
@@ -48,8 +54,11 @@ export async function handleChatCompletion(request, openai, defaultModel) {
     const extra = { server_version: SERVER_VERSION };
     if (cacheMeta)
         extra.cache = cacheMeta;
+    const capped = capResultText(extracted.text);
+    if (capped.truncated)
+        extra.result_truncated = true;
     return {
-        content: [{ type: 'text', text: extracted.text }],
+        content: [{ type: 'text', text: capped.text }],
         _meta: buildCompletionMeta(extracted, {
             includeReasoning: wantsReasoning,
             extra,

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

@@ -1,8 +1,9 @@
 import type OpenAI from 'openai';
 import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions.js';
+import { type ToolErrorResult } from '../errors.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";
+export declare const DEFAULT_CHAT_MODEL = "google/gemma-4-26b-a4b-it:free";
 /** Shared request shape for sync and async chat completion tools. */
 export interface ChatToolRequest extends CacheOptions {
     model?: string;
@@ -15,6 +16,8 @@ export interface ChatToolRequest extends CacheOptions {
     web_max_results?: number;
 }
 export declare function readIncludeReasoningDefault(): boolean;
+export declare function validateChatMessages(messages: ChatCompletionMessageParam[] | undefined): ToolErrorResult | null;
+export declare function validateMaxTokens(max_tokens: number | undefined): ToolErrorResult | null;
 export declare function buildChatCompletionBody(input: ChatToolRequest & {
     model: string;
 }): Record<string, unknown>;

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

@@ -1,10 +1,38 @@
+import { ErrorCode, toolError } from '../errors.js';
 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 const DEFAULT_CHAT_MODEL = 'google/gemma-4-26b-a4b-it:free';
 export function readIncludeReasoningDefault() {
     const raw = (process.env.OPENROUTER_INCLUDE_REASONING ?? '').trim().toLowerCase();
     return raw === '1' || raw === 'true' || raw === 'yes';
 }
+export function validateChatMessages(messages) {
+    if (!messages?.length) {
+        return toolError(ErrorCode.INVALID_INPUT, 'Messages array cannot be empty.');
+    }
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        const role = msg.role;
+        if (typeof role !== 'string' || role.trim().length === 0) {
+            return toolError(ErrorCode.INVALID_INPUT, `Message at index ${i} has an empty or missing role.`);
+        }
+        if ('content' in msg && msg.content === null) {
+            return toolError(ErrorCode.INVALID_INPUT, `Message at index ${i} has null content.`);
+        }
+    }
+    return null;
+}
+export function validateMaxTokens(max_tokens) {
+    if (max_tokens === undefined)
+        return null;
+    if (typeof max_tokens !== 'number' ||
+        !Number.isFinite(max_tokens) ||
+        max_tokens <= 0 ||
+        !Number.isInteger(max_tokens)) {
+        return toolError(ErrorCode.INVALID_INPUT, 'max_tokens must be a positive integer.');
+    }
+    return null;
+}
 export function buildChatCompletionBody(input) {
     const providerBody = buildProviderBody(mergeProviderOptions(readProviderDefaults(), input.provider));
     const effectiveMaxTokens = resolveMaxTokens(input.max_tokens);

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

@@ -12,6 +12,11 @@ export interface ExtractedText {
     reasoning?: string;
     usage?: ChatCompletion['usage'];
 }
+export declare function readMaxResultTextChars(): number;
+export declare function capResultText(text: string): {
+    text: string;
+    truncated: boolean;
+};
 export declare function extractCompletionText(completion: ChatCompletion): ExtractedText;
 /**
  * If the extracted response is reasoning-only and was cut off by
@@ -21,17 +26,6 @@ export declare function extractCompletionText(completion: ChatCompletion): Extra
  */
 export declare function detectReasoningCutoff(extracted: ExtractedText): ToolErrorResult | null;
 export declare function toUsageMeta(usage: ChatCompletion['usage'] | undefined): Record<string, unknown> | undefined;
-/**
- * Build the common `_meta` shape for chat-completion-derived tools.
- * Folds in:
- *  - normalized and native finish reasons (from the choice)
- *  - optional `reasoning` trace (when the caller opted in)
- *  - token usage (prompt / completion / total)
- *  - server version stamp
- *
- * Caller can pass `extra` to merge additional keys (cache metadata,
- * content_is_untrusted, etc.) without repeating this boilerplate.
- */
 export interface BuildMetaOptions {
     includeReasoning?: boolean;
     extra?: Record<string, unknown>;

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

@@ -1,4 +1,23 @@
 import { ErrorCode, toolError } from '../errors.js';
+/** Default cap for text returned in tool content / _meta (chars). Set OPENROUTER_MAX_RESULT_TEXT_CHARS=0 to disable. */
+const DEFAULT_MAX_RESULT_TEXT_CHARS = 512_000;
+export function readMaxResultTextChars() {
+    const raw = process.env.OPENROUTER_MAX_RESULT_TEXT_CHARS;
+    if (raw === undefined || raw === '')
+        return DEFAULT_MAX_RESULT_TEXT_CHARS;
+    if (raw === '0')
+        return 0;
+    const n = parseInt(raw, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_MAX_RESULT_TEXT_CHARS;
+}
+export function capResultText(text) {
+    const max = readMaxResultTextChars();
+    if (max <= 0 || text.length <= max)
+        return { text, truncated: false };
+    const omitted = text.length - max;
+    const marker = `\n\n[… truncated — ${omitted} chars omitted; set OPENROUTER_MAX_RESULT_TEXT_CHARS=0 to disable]`;
+    return { text: text.slice(0, max) + marker, truncated: true };
+}
 function extractReasoning(msg) {
     if (typeof msg.reasoning === 'string' && msg.reasoning.length > 0)
         return msg.reasoning;
@@ -12,41 +31,40 @@ function extractReasoning(msg) {
     }
     return undefined;
 }
-export function extractCompletionText(completion) {
-    const choice = completion.choices?.[0];
-    const msg = choice?.message;
-    const finishReason = choice?.finish_reason;
-    const nativeFinishReason = choice?.native_finish_reason ?? undefined;
-    const usage = completion.usage ?? undefined;
-    if (!msg) {
-        return {
-            text: '',
-            reasonedOnly: false,
-            finishReason,
-            nativeFinishReason: nativeFinishReason ?? undefined,
-            usage,
-        };
-    }
-    const { content } = msg;
-    const reasoning = extractReasoning(msg);
-    if (typeof content === 'string' && content.length > 0) {
-        return {
-            text: content,
-            reasonedOnly: false,
-            finishReason,
-            nativeFinishReason: nativeFinishReason ?? undefined,
-            reasoning,
-            usage,
-        };
-    }
+function extractContentText(content) {
+    if (typeof content === 'string' && content.length > 0)
+        return content;
     if (Array.isArray(content)) {
         const parts = content
             .filter((p) => p.type === 'text' && typeof p.text === 'string')
             .map((p) => p.text ?? '');
-        const joined = parts.join('');
-        if (joined.length > 0) {
+        return parts.join('');
+    }
+    return '';
+}
+function emptyExtracted(finishReason, nativeFinishReason, usage) {
+    return {
+        text: '',
+        reasonedOnly: false,
+        finishReason,
+        nativeFinishReason,
+        usage,
+    };
+}
+export function extractCompletionText(completion) {
+    try {
+        const choice = completion.choices?.[0];
+        const msg = choice?.message;
+        const finishReason = choice?.finish_reason;
+        const nativeFinishReason = choice?.native_finish_reason ?? undefined;
+        const usage = completion.usage ?? undefined;
+        if (!msg) {
+            return emptyExtracted(finishReason, nativeFinishReason ?? undefined, usage);
+        }
+        const reasoning = extractReasoning(msg);
+        if (typeof msg.refusal === 'string' && msg.refusal.length > 0) {
             return {
-                text: joined,
+                text: msg.refusal,
                 reasonedOnly: false,
                 finishReason,
                 nativeFinishReason: nativeFinishReason ?? undefined,
@@ -54,24 +72,32 @@ export function extractCompletionText(completion) {
                 usage,
             };
         }
+        const contentText = extractContentText(msg.content);
+        if (contentText.length > 0) {
+            return {
+                text: contentText,
+                reasonedOnly: false,
+                finishReason,
+                nativeFinishReason: nativeFinishReason ?? undefined,
+                reasoning,
+                usage,
+            };
+        }
+        if (reasoning && reasoning.length > 0) {
+            return {
+                text: reasoning,
+                reasonedOnly: true,
+                finishReason,
+                nativeFinishReason: nativeFinishReason ?? undefined,
+                reasoning,
+                usage,
+            };
+        }
+        return emptyExtracted(finishReason, nativeFinishReason ?? undefined, usage);
     }
-    if (reasoning && reasoning.length > 0) {
-        return {
-            text: reasoning,
-            reasonedOnly: true,
-            finishReason,
-            nativeFinishReason: nativeFinishReason ?? undefined,
-            reasoning,
-            usage,
-        };
+    catch {
+        return emptyExtracted(undefined, undefined, undefined);
     }
-    return {
-        text: '',
-        reasonedOnly: false,
-        finishReason,
-        nativeFinishReason: nativeFinishReason ?? undefined,
-        usage,
-    };
 }
 /**
  * If the extracted response is reasoning-only and was cut off by
@@ -115,7 +141,10 @@ export function buildCompletionMeta(extracted, opts = {}) {
         meta.native_finish_reason = extracted.nativeFinishReason;
     }
     if (opts.includeReasoning && extracted.reasoning && !extracted.reasonedOnly) {
-        meta.reasoning = extracted.reasoning;
+        const capped = capResultText(extracted.reasoning);
+        meta.reasoning = capped.text;
+        if (capped.truncated)
+            meta.reasoning_truncated = true;
     }
     const usageMeta = toUsageMeta(extracted.usage);
     if (usageMeta)

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

@@ -7,6 +7,19 @@ export declare function readEnvInt(name: string, fallback: number, min?: number)
 export declare function isBlockedIPv4(ip: string): boolean;
 /** SSRF block list for IPv6 literals (private/reserved ranges). */
 export declare function isBlockedIPv6(ip: string): boolean;
+export interface PinnedAddress {
+    address: string;
+    family: 4 | 6;
+}
+type DnsLookupHook = (host: string) => Promise<PinnedAddress[]>;
+/** @internal Test seam — never active in production. */
+export declare function __setFetchUtilsTestHooks(hooks: {
+    dnsLookup?: DnsLookupHook | null;
+    trustedCa?: string;
+    allowLoopbackResolution?: boolean;
+}): void;
+/** @internal Test seam — never active in production. */
+export declare function __resetFetchUtilsTestHooks(): void;
 /** Resolve hostname and ensure the resolved address is not private/link-local. */
 export declare function assertUrlSafeForFetch(urlString: string): Promise<URL>;
 /**
@@ -32,3 +45,4 @@ export declare function fetchHttpResource(urlString: string, opts: FetchOptions)
     buffer: Buffer;
     contentType: string | null;
 }>;
+export {};