@stabgan/openrouter-mcp-multimodal 4.7.0 → 5.0.0

package/dist/tool-handlers/openrouter-errors.js

@@ -2,6 +2,17 @@
  * Map OpenRouter / OpenAI SDK errors to our closed `ErrorCode` enum.
  */
 import { ErrorCode, toolError } from '../errors.js';
+const AUTH_SUGGESTIONS = [
+    'Verify OPENROUTER_API_KEY is set and matches https://openrouter.ai/keys',
+    'Ensure the key has not been revoked or expired',
+];
+/** Strip bearer tokens and OpenRouter key material from user-visible messages. */
+export function sanitizeErrorMessage(msg) {
+    return msg
+        .replace(/Bearer\s+\S+/gi, 'Bearer [REDACTED]')
+        .replace(/sk-or-v\d+-[\w-]+/gi, '[REDACTED]')
+        .replace(/Authorization:\s*\S+/gi, 'Authorization: [REDACTED]');
+}
 function extractRetryAfterSeconds(err) {
     if (typeof err !== 'object' || err === null)
         return undefined;
@@ -18,22 +29,29 @@ function extractRetryAfterSeconds(err) {
     const raw = getHeader(e.headers) ?? getHeader(e.response?.headers);
     if (!raw)
         return undefined;
-    const n = Number(raw);
-    if (Number.isFinite(n) && n >= 0)
-        return n;
+    const asInt = parseInt(raw, 10);
+    if (Number.isFinite(asInt) && asInt >= 0)
+        return asInt;
+    const asDate = Date.parse(raw);
+    if (Number.isFinite(asDate)) {
+        const deltaSec = Math.ceil((asDate - Date.now()) / 1000);
+        return deltaSec > 0 ? deltaSec : 0;
+    }
     return undefined;
 }
 function extractStatus(err) {
     if (typeof err !== 'object' || err === null)
         return undefined;
-    const s = err.status;
-    if (typeof s === 'number')
-        return s;
-    const c = err.code;
-    if (typeof c === 'number')
-        return c;
-    if (typeof c === 'string' && /^\d{3}$/.test(c))
-        return parseInt(c, 10);
+    const e = err;
+    if (typeof e.status === 'number')
+        return e.status;
+    if (typeof e.code === 'number')
+        return e.code;
+    if (typeof e.code === 'string' && /^\d{3}$/.test(e.code))
+        return parseInt(e.code, 10);
+    const nested = e.error;
+    if (nested && typeof nested === 'object' && typeof nested.code === 'number')
+        return nested.code;
     if (err instanceof Error) {
         const m = err.message.match(/\bHTTP (\d{3})\b/);
         if (m)
@@ -41,27 +59,116 @@ function extractStatus(err) {
     }
     return undefined;
 }
+function extractNestedError(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    const nested = err.error;
+    if (!nested)
+        return undefined;
+    return nested;
+}
 function extractMessage(err) {
+    let msg;
     if (err instanceof Error) {
-        const nested = err.error;
+        const nested = extractNestedError(err);
         if (nested && typeof nested === 'object' && typeof nested.message === 'string') {
-            return `${err.message} — ${nested.message}`;
+            msg = `${err.message} — ${nested.message}`;
+        }
+        else if (typeof nested === 'string') {
+            msg = `${err.message} — ${nested}`;
         }
-        if (typeof nested === 'string')
-            return `${err.message} — ${nested}`;
-        return err.message;
+        else {
+            msg = err.message;
+        }
+    }
+    else if (typeof err === 'string') {
+        msg = err;
     }
-    if (typeof err === 'string')
-        return err;
-    return 'unknown error';
+    else if (typeof err === 'object' && err !== null) {
+        const e = err;
+        if (typeof e.message === 'string') {
+            msg = e.message;
+        }
+        else {
+            const nested = extractNestedError(err);
+            if (nested && typeof nested === 'object' && typeof nested.message === 'string') {
+                msg = nested.message;
+            }
+            else if (typeof nested === 'string') {
+                msg = nested;
+            }
+            else {
+                msg = 'unknown error';
+            }
+        }
+    }
+    else {
+        msg = 'unknown error';
+    }
+    return sanitizeErrorMessage(msg);
+}
+function extractErrorType(err) {
+    const nested = extractNestedError(err);
+    if (nested && typeof nested === 'object') {
+        if (typeof nested.error_type === 'string')
+            return nested.error_type;
+        if (typeof nested.type === 'string')
+            return nested.type;
+    }
+    return undefined;
+}
+function isAuthFailure(status, lower, errorType) {
+    if (status === 401)
+        return true;
+    if (errorType === 'authentication' || errorType === 'authentication_error')
+        return true;
+    return (lower.includes('invalid api key') ||
+        lower.includes('invalid credentials') ||
+        lower.includes('invalid authentication') ||
+        lower.includes('no auth credentials') ||
+        lower.includes('missing api key') ||
+        lower.includes('unauthorized') ||
+        lower.includes('authentication failed') ||
+        lower.includes('user not found') ||
+        (status === 403 &&
+            (lower.includes('invalid api key') ||
+                lower.includes('invalid credentials') ||
+                lower.includes('authentication'))));
+}
+function isModelNotFound(status, lower) {
+    if (status === 404)
+        return true;
+    return (lower.includes('model') &&
+        (lower.includes('does not exist') ||
+            lower.includes('not found') ||
+            lower.includes('invalid model')));
+}
+function isGuardrailOrPolicy(lower) {
+    return (lower.includes('content policy') ||
+        lower.includes('moderation') ||
+        lower.includes('refused') ||
+        lower.includes('prompt injection') ||
+        lower.includes('guardrail') ||
+        lower.includes('request blocked') ||
+        lower.includes('blocked:'));
+}
+function looksLikeHtml(msg) {
+    const t = msg.trimStart().toLowerCase();
+    return t.startsWith('<!doctype') || t.startsWith('<html');
 }
 /** Classify upstream errors into the closed `ErrorCode` set. */
 export function classifyUpstreamError(err, contextMessage) {
     const rawMsg = extractMessage(err);
     const status = extractStatus(err);
+    const errorType = extractErrorType(err);
     const lower = rawMsg.toLowerCase();
     const fullMsg = contextMessage ? `${contextMessage}: ${rawMsg}` : rawMsg;
     const retryAfterSeconds = extractRetryAfterSeconds(err);
+    if (looksLikeHtml(rawMsg)) {
+        return toolError(ErrorCode.UPSTREAM_HTTP, contextMessage
+            ? `${contextMessage}: upstream returned an HTML error page`
+            : 'upstream returned an HTML error page', { status }, { suggestions: ['Retry after a brief delay', 'Check https://status.openrouter.ai'] });
+    }
     if (lower.includes('insufficient balance') ||
         lower.includes('insufficient credits') ||
         lower.includes('requires more credits') ||
@@ -82,10 +189,7 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    if (lower.includes('model') &&
-        (lower.includes('does not exist') ||
-            lower.includes('not found') ||
-            lower.includes('invalid model'))) {
+    if (isModelNotFound(status, lower)) {
         return toolError(ErrorCode.MODEL_NOT_FOUND, fullMsg, { status }, {
             suggestions: [
                 'Use search_models to discover valid model ids',
@@ -93,13 +197,6 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    if (lower.includes('content policy') ||
-        lower.includes('moderation') ||
-        lower.includes('refused')) {
-        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' }, {
-            suggestions: ['Rephrase the prompt', 'Try a different provider via provider.order'],
-        });
-    }
     if (status === 429 || lower.includes('rate limit')) {
         return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' }, {
             suggestions: [
@@ -119,8 +216,18 @@ export function classifyUpstreamError(err, contextMessage) {
             suggestions: ['Retry', 'Raise max_wait_ms or max_tokens'],
         });
     }
+    if (isAuthFailure(status, lower, errorType)) {
+        return toolError(ErrorCode.INVALID_CREDENTIALS, fullMsg, { status, reason: 'auth' }, { suggestions: [...AUTH_SUGGESTIONS] });
+    }
+    if (isGuardrailOrPolicy(lower) || status === 403) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' }, {
+            suggestions: ['Rephrase the prompt', 'Try a different provider via provider.order'],
+        });
+    }
     if (typeof status === 'number' && status >= 400 && status < 500) {
-        return toolError(ErrorCode.INVALID_INPUT, fullMsg, { status });
+        return toolError(ErrorCode.INVALID_INPUT, fullMsg, { status }, {
+            suggestions: ['Verify request parameters against OpenRouter docs'],
+        });
     }
     if (typeof status === 'number' && status >= 500) {
         return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg, { status }, {

package/dist/tool-handlers/path-safety.js

@@ -33,6 +33,22 @@ function isUnsafeMode() {
     const v = process.env.OPENROUTER_ALLOW_UNSAFE_PATHS;
     return v === '1' || v?.toLowerCase() === 'true';
 }
+function pathHasNullByte(p) {
+    return p.includes('\0');
+}
+function withRootSep(rootReal) {
+    return rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
+}
+/** Prefix check; case-insensitive on Windows (drive letter / path casing). */
+function isInsideRoot(resolved, rootReal) {
+    const withSep = withRootSep(rootReal);
+    if (process.platform === 'win32') {
+        const lower = resolved.toLowerCase();
+        const rootLower = rootReal.toLowerCase();
+        return lower === rootLower || lower.startsWith(withRootSep(rootLower));
+    }
+    return resolved === rootReal || resolved.startsWith(withSep);
+}
 export class UnsafeOutputPathError extends Error {
     constructor(message) {
         super(message);
@@ -49,23 +65,26 @@ export async function resolveSafeOutputPath(savePath) {
         await fs.mkdir(path.dirname(abs), { recursive: true });
         return abs;
     }
+    if (pathHasNullByte(savePath)) {
+        throw new UnsafeOutputPathError('save_path contains a null byte');
+    }
     const root = getOutputRoot();
     const rootReal = await fs.realpath(root).catch(() => path.resolve(root));
     const candidate = path.isAbsolute(savePath)
         ? path.resolve(savePath)
         : path.resolve(rootReal, savePath);
-    const withSep = rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
     const candidateDir = path.dirname(candidate);
     const existingAncestor = await findExistingAncestor(candidateDir);
     const ancestorReal = await fs.realpath(existingAncestor);
-    if (!(ancestorReal === rootReal || ancestorReal.startsWith(withSep))) {
-        throw new UnsafeOutputPathError(`save_path resolves outside OPENROUTER_OUTPUT_DIR (${rootReal}). ` +
+    if (!isInsideRoot(ancestorReal, rootReal)) {
+        throw new UnsafeOutputPathError(`save_path resolves outside OPENROUTER_OUTPUT_DIR. ` +
             `Set OPENROUTER_OUTPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.`);
     }
     await fs.mkdir(candidateDir, { recursive: true });
     const parentReal = await fs.realpath(candidateDir);
-    if (!(parentReal === rootReal || parentReal.startsWith(withSep))) {
-        throw new UnsafeOutputPathError(`save_path escapes OPENROUTER_OUTPUT_DIR via symlink (${rootReal}).`);
+    if (!isInsideRoot(parentReal, rootReal)) {
+        throw new UnsafeOutputPathError('save_path escapes OPENROUTER_OUTPUT_DIR via symlink. ' +
+            'Set OPENROUTER_OUTPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.');
     }
     return path.join(parentReal, path.basename(candidate));
 }
@@ -108,23 +127,37 @@ export async function resolveSafeInputPath(inputPath) {
     if (isUnsafeMode()) {
         return path.resolve(inputPath);
     }
+    if (pathHasNullByte(inputPath)) {
+        throw new UnsafeOutputPathError('input path contains a null byte');
+    }
     const root = getInputRoot();
     const rootReal = await fs.realpath(root).catch(() => path.resolve(root));
-    const withSep = rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
     const abs = path.isAbsolute(inputPath)
         ? path.resolve(inputPath)
         : path.resolve(rootReal, inputPath);
-    let canonical;
-    try {
-        canonical = await fs.realpath(abs);
+    const existingAncestor = await findExistingAncestor(abs);
+    const ancestorReal = await fs.realpath(existingAncestor);
+    if (!isInsideRoot(ancestorReal, rootReal)) {
+        throw new UnsafeOutputPathError(`input path resolves outside OPENROUTER_INPUT_DIR: ${inputPath}. ` +
+            'Set OPENROUTER_INPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.');
     }
-    catch {
-        canonical = abs;
+    try {
+        const canonical = await fs.realpath(abs);
+        if (!isInsideRoot(canonical, rootReal)) {
+            throw new UnsafeOutputPathError(`input path resolves outside OPENROUTER_INPUT_DIR: ${inputPath}. ` +
+                'Set OPENROUTER_INPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.');
+        }
+        return canonical;
     }
-    if (!(canonical === rootReal || canonical.startsWith(withSep))) {
-        throw new UnsafeOutputPathError(`input path resolves outside OPENROUTER_INPUT_DIR (${rootReal}): ${inputPath}`);
+    catch (err) {
+        if (err instanceof UnsafeOutputPathError)
+            throw err;
+        if (!isInsideRoot(abs, rootReal)) {
+            throw new UnsafeOutputPathError(`input path resolves outside OPENROUTER_INPUT_DIR: ${inputPath}. ` +
+                'Set OPENROUTER_INPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.');
+        }
+        return abs;
     }
-    return abs;
 }
 export function isToolErrorResult(result) {
     return 'isError' in result;
@@ -158,18 +191,17 @@ export async function resolveSafeJobStatusPath(jobsDir, jobId) {
     if (!isValidJobId(jobId))
         return null;
     const rootReal = await fs.realpath(jobsDir).catch(() => path.resolve(jobsDir));
-    const withSep = rootReal.endsWith(path.sep) ? rootReal : rootReal + path.sep;
     const jobDirCandidate = path.resolve(jobsDir, jobId);
     let jobDirReal;
     try {
         jobDirReal = await fs.realpath(jobDirCandidate);
     }
     catch {
-        if (!(jobDirCandidate === rootReal || jobDirCandidate.startsWith(withSep)))
+        if (!isInsideRoot(jobDirCandidate, rootReal))
             return null;
         return path.join(jobDirCandidate, 'status.json');
     }
-    if (!(jobDirReal === rootReal || jobDirReal.startsWith(withSep)))
+    if (!isInsideRoot(jobDirReal, rootReal))
         return null;
     return path.join(jobDirReal, 'status.json');
 }

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

@@ -1,2 +1,4 @@
 /** Strip existing extension (if any) and append a new one. */
 export declare function replaceExtension(filePath: string, newExt: string): string;
+/** Write bytes atomically via a same-directory temp file and rename. */
+export declare function writeOutputFile(target: string, data: Buffer): Promise<void>;

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

@@ -1,7 +1,20 @@
 import { extname } from 'node:path';
+import { promises as fs } from 'node:fs';
 /** Strip existing extension (if any) and append a new one. */
 export function replaceExtension(filePath, newExt) {
     const current = extname(filePath);
     const base = current ? filePath.slice(0, -current.length) : filePath;
     return `${base}.${newExt}`;
 }
+/** Write bytes atomically via a same-directory temp file and rename. */
+export async function writeOutputFile(target, data) {
+    const tmp = `${target}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        await fs.writeFile(tmp, data);
+        await fs.rename(tmp, target);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => undefined);
+        throw err;
+    }
+}

package/dist/tool-handlers/provider-routing.d.ts

@@ -5,6 +5,8 @@ export interface ProviderRoutingOptions {
     quantizations?: string[];
     /** Exclude these provider slugs (e.g. `['openai', 'anthropic']`). */
     ignore?: string[];
+    /** Allow only these provider slugs for the request. */
+    only?: string[];
     /** Sort providers by this criterion. */
     sort?: ProviderSort;
     /** Prioritized provider list (e.g. `['openai/gpt-4o', 'anthropic/claude-3-opus']`). */

package/dist/tool-handlers/provider-routing.js

@@ -24,7 +24,7 @@ function parseJsonArray(raw, name) {
             return parsed.length > 0 ? parsed : undefined;
         }
         catch (err) {
-            throw new Error(`${name}: malformed JSON array (${err instanceof Error ? err.message : String(err)})`);
+            throw new Error(`${name}: malformed JSON array (${err instanceof Error ? err.message : String(err)})`, { cause: err });
         }
     }
     return parseCsv(trimmed);
@@ -66,6 +66,16 @@ export function readProviderDefaults() {
     const ignore = parseCsv(env.OPENROUTER_PROVIDER_IGNORE);
     if (ignore)
         out.ignore = ignore;
+    try {
+        const only = parseJsonArray(env.OPENROUTER_PROVIDER_ONLY, 'OPENROUTER_PROVIDER_ONLY');
+        if (only)
+            out.only = only;
+    }
+    catch (err) {
+        logger.warn('OPENROUTER_PROVIDER_ONLY ignored', {
+            err: err instanceof Error ? err.message : String(err),
+        });
+    }
     const sort = parseSort(env.OPENROUTER_PROVIDER_SORT);
     if (sort)
         out.sort = sort;

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

@@ -11,7 +11,4 @@ export declare function handleRerankDocuments(request: {
     params: {
         arguments: RerankDocumentsRequest;
     };
-}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | import("./structured-output.js").StructuredResult<{
-    model: string;
-    results: Record<string, unknown>[];
-}>>;
+}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | import("./structured-output.js").StructuredResult<unknown>>;

package/dist/tool-handlers/rerank.js

@@ -1,7 +1,39 @@
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { buildStructuredResult } from './structured-output.js';
-const DEFAULT_MODEL = 'cohere/rerank-english-v3.0';
+import { capResultText } from './completion-utils.js';
+const DEFAULT_MODEL = 'cohere/rerank-v3.5';
+function isValidDocumentIndex(index, documentCount) {
+    return (typeof index === 'number' && Number.isInteger(index) && index >= 0 && index < documentCount);
+}
+function normalizeRerankResults(response, documents, returnDocuments, modelFallback) {
+    const invalid = (response.results ?? []).find((r) => !isValidDocumentIndex(r.index, documents.length));
+    if (invalid) {
+        return toolError(ErrorCode.INTERNAL, `Rerank API returned invalid document index ${String(invalid.index)} (expected 0–${documents.length - 1}).`);
+    }
+    const normalized = (response.results ?? []).map((r) => {
+        const score = typeof r.score === 'number' ? r.score : r.relevance_score;
+        const out = { index: r.index, score };
+        if (returnDocuments) {
+            const rawDoc = typeof r.document === 'string' ? r.document : (r.document?.text ?? documents[r.index]);
+            const capped = capResultText(rawDoc);
+            out.document = capped.text;
+            if (capped.truncated)
+                out.document_truncated = true;
+        }
+        return out;
+    });
+    const payload = {
+        model: response.model ?? modelFallback,
+        results: normalized,
+    };
+    const jsonText = JSON.stringify(payload, null, 2);
+    const cappedJson = capResultText(jsonText);
+    if (cappedJson.truncated) {
+        return toolError(ErrorCode.RESOURCE_TOO_LARGE, 'Rerank result exceeds OPENROUTER_MAX_RESULT_TEXT_CHARS. Set it to 0 to disable or raise the limit.', { result_truncated: true });
+    }
+    return buildStructuredResult(payload, response.usage ? { usage: response.usage } : {});
+}
 export async function handleRerankDocuments(request, apiClient) {
     const args = request.params.arguments ?? { query: '', documents: [] };
     const { query, documents, model, top_n, return_documents } = args;
@@ -14,10 +46,19 @@ export async function handleRerankDocuments(request, apiClient) {
     if (documents.some((d) => typeof d !== 'string')) {
         return toolError(ErrorCode.INVALID_INPUT, 'every document must be a string.');
     }
+    if (top_n !== undefined) {
+        if (typeof top_n !== 'number' || !Number.isFinite(top_n)) {
+            return toolError(ErrorCode.INVALID_INPUT, 'top_n must be a finite number.');
+        }
+        if (top_n < 1) {
+            return toolError(ErrorCode.INVALID_INPUT, 'top_n must be at least 1 when specified.');
+        }
+    }
+    const effectiveModel = model || DEFAULT_MODEL;
     let response;
     try {
         response = await apiClient.rerank({
-            model: model || DEFAULT_MODEL,
+            model: effectiveModel,
             query,
             documents,
             top_n,
@@ -26,20 +67,8 @@ export async function handleRerankDocuments(request, apiClient) {
     catch (err) {
         return classifyUpstreamError(err, 'rerank');
     }
-    const normalized = (response.results ?? []).map((r) => {
-        const score = typeof r.score === 'number' ? r.score : r.relevance_score;
-        const out = { index: r.index, score };
-        if (return_documents) {
-            const doc = typeof r.document === 'string' ? r.document : (r.document?.text ?? documents[r.index]);
-            out.document = doc;
-        }
-        return out;
-    });
     try {
-        return buildStructuredResult({
-            model: response.model ?? model ?? DEFAULT_MODEL,
-            results: normalized,
-        }, response.usage ? { usage: response.usage } : {});
+        return normalizeRerankResults(response, documents, return_documents === true, effectiveModel);
     }
     catch (err) {
         return toolErrorFrom(ErrorCode.INTERNAL, err, 'rerank');

package/dist/tool-handlers/search-models.js

@@ -1,8 +1,8 @@
+import { clampLimit, clampOffset } from '../model-cache.js';
 import { ErrorCode, toolErrorFrom } from '../errors.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
 import { buildStructuredResult } from './structured-output.js';
 const DEFAULT_LIMIT = 20;
-const MAX_LIMIT = 50;
 export async function handleSearchModels(request, apiClient, modelCache) {
     try {
         await modelCache.ensureFresh(() => apiClient.getModels());
@@ -12,8 +12,8 @@ export async function handleSearchModels(request, apiClient, modelCache) {
     }
     try {
         const args = request.params.arguments ?? {};
-        const limit = Math.min(Math.max(1, args.limit ?? DEFAULT_LIMIT), MAX_LIMIT);
-        const offset = Math.max(0, args.offset ?? 0);
+        const limit = clampLimit(args.limit ?? DEFAULT_LIMIT, DEFAULT_LIMIT);
+        const offset = clampOffset(args.offset ?? 0);
         const { page, total } = modelCache.searchPaginated({
             query: args.query,
             provider: args.provider,

package/dist/tool-handlers/speech-to-text.d.ts

@@ -1,3 +1,4 @@
+/** Dedicated POST /api/v1/audio/transcriptions — Whisper, GPT-4o Transcribe, Voxtral. */
 import type { OpenRouterAPIClient } from '../openrouter-api.js';
 import { type CacheOptions } from './cache.js';
 export interface SpeechToTextRequest extends CacheOptions {

package/dist/tool-handlers/speech-to-text.js

@@ -1,63 +1,18 @@
-/** Dedicated POST /api/v1/audio/transcriptions — Whisper, GPT-4o Transcribe, Voxtral. */
-import { promises as fs } from 'node:fs';
-import path from 'node:path';
-import { resolveSafeInputPath, UnsafeOutputPathError } from './path-safety.js';
-import { fetchHttpResource } from './fetch-utils.js';
+import { STT_RESPONSE_FORMATS } from '../tool-definitions.js';
+import { UnsafeOutputPathError } from './path-safety.js';
+import { resolveSpeechToTextAudio } from './audio-utils.js';
 import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
 import { classifyUpstreamError } from './openrouter-errors.js';
-import { buildCacheHeaders } from './cache.js';
+import { buildCacheHeaders, validateCacheOptions } from './cache.js';
 const DEFAULT_MODEL = 'openai/whisper-1';
-const VALID_RESPONSE_FORMATS = new Set(['json', 'text', 'srt', 'verbose_json', 'vtt']);
-/** Infer audio format from file extension. */
-function audioFormatFromExt(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:
-            return 'mp3';
+const VALID_RESPONSE_FORMATS = new Set(STT_RESPONSE_FORMATS);
+function formatTranscriptionContent(response, responseFormat) {
+    if (responseFormat === 'verbose_json') {
+        return JSON.stringify(response, null, 2);
     }
-}
-async function resolveAudioInput(audioPath) {
-    const trimmed = audioPath.trim();
-    if (!trimmed)
-        throw new Error('audio_path is empty');
-    if (trimmed.startsWith('data:')) {
-        const match = trimmed.match(/^data:audio\/([^;,]+)(?:;[^,]*)*;base64,(.+)$/);
-        if (!match)
-            throw new Error('Invalid audio data URL format');
-        return { data: match[2], format: match[1] };
-    }
-    if (/^https?:\/\//i.test(trimmed)) {
-        const { buffer, contentType } = await fetchHttpResource(trimmed, {
-            timeoutMs: 60_000,
-            maxBytes: 100 * 1024 * 1024,
-            maxRedirects: 8,
-        });
-        const format = contentType?.match(/audio\/(\w+)/)?.[1] || 'mp3';
-        return { data: buffer.toString('base64'), format };
-    }
-    const abs = await resolveSafeInputPath(trimmed);
-    const buf = await fs.readFile(abs);
-    const ext = path.extname(abs);
-    const format = audioFormatFromExt(ext);
-    return { data: buf.toString('base64'), format };
+    return response.text ?? null;
 }
 export async function handleSpeechToText(request, apiClient) {
     const args = request.params.arguments ?? {};
@@ -68,6 +23,12 @@ export async function handleSpeechToText(request, apiClient) {
     if (response_format && !VALID_RESPONSE_FORMATS.has(response_format)) {
         return toolError(ErrorCode.INVALID_INPUT, `response_format '${response_format}' is not supported. Valid: ${[...VALID_RESPONSE_FORMATS].join(', ')}.`);
     }
+    if (typeof temperature === 'number' && (temperature < 0 || temperature > 1)) {
+        return toolError(ErrorCode.INVALID_INPUT, 'temperature must be between 0 and 1 (inclusive).');
+    }
+    const cacheError = validateCacheOptions({ cache, cache_ttl, cache_clear });
+    if (cacheError)
+        return cacheError;
     logger.audit('speech_to_text.start', {
         model: model || DEFAULT_MODEL,
         audio_path: audio_path.startsWith('data:') ? 'data_url' : audio_path.slice(0, 80),
@@ -76,7 +37,7 @@ export async function handleSpeechToText(request, apiClient) {
     });
     let audioInput;
     try {
-        audioInput = await resolveAudioInput(audio_path);
+        audioInput = await resolveSpeechToTextAudio(audio_path);
     }
     catch (err) {
         if (err instanceof UnsafeOutputPathError)
@@ -84,6 +45,12 @@ export async function handleSpeechToText(request, apiClient) {
         const msg = err instanceof Error ? err.message : String(err);
         if (msg.includes('Blocked host'))
             return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
+        if (msg.toLowerCase().includes('too large')) {
+            return toolErrorFrom(ErrorCode.RESOURCE_TOO_LARGE, err);
+        }
+        if (msg.toLowerCase().includes('unsupported')) {
+            return toolErrorFrom(ErrorCode.UNSUPPORTED_FORMAT, err);
+        }
         return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
     }
     const body = {
@@ -107,7 +74,7 @@ export async function handleSpeechToText(request, apiClient) {
     catch (err) {
         return classifyUpstreamError(err, 'speech_to_text');
     }
-    const text = response.text;
+    const text = formatTranscriptionContent(response, response_format);
     if (!text) {
         return toolError(ErrorCode.INTERNAL, 'Transcription returned no text.', {
             response_keys: Object.keys(response),

package/dist/tool-handlers/text-to-speech.d.ts

@@ -13,7 +13,7 @@ export declare function handleTextToSpeech(request: {
     params: {
         arguments: TextToSpeechRequest;
     };
-}, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
+}, apiClient: OpenRouterAPIClient): Promise<{
     content: import("./tool-result-payload.js").BinaryToolContent[];
     _meta: Record<string, unknown>;
 }>;