@stabgan/openrouter-mcp-multimodal 4.6.1 → 4.7.0

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

@@ -1,8 +1,5 @@
 /**
- * Shared mapping from OpenRouter / OpenAI SDK error shapes to our closed
- * `ErrorCode` enum. Every tool handler that calls the OpenAI client routes
- * its `catch` block through `classifyUpstreamError` so error taxonomies
- * don't drift.
+ * Map OpenRouter / OpenAI SDK errors to our closed `ErrorCode` enum.
  */
 import { ErrorCode, toolError } from '../errors.js';
 function extractRetryAfterSeconds(err) {
@@ -24,8 +21,6 @@ function extractRetryAfterSeconds(err) {
     const n = Number(raw);
     if (Number.isFinite(n) && n >= 0)
         return n;
-    // Retry-After can also be an HTTP-date; return undefined for those (caller
-    // can still retry on its own backoff schedule).
     return undefined;
 }
 function extractStatus(err) {
@@ -34,14 +29,11 @@ function extractStatus(err) {
     const s = err.status;
     if (typeof s === 'number')
         return s;
-    // openai-node sometimes puts the status in `code` for `APIError`.
     const c = err.code;
     if (typeof c === 'number')
         return c;
     if (typeof c === 'string' && /^\d{3}$/.test(c))
         return parseInt(c, 10);
-    // Fall back: parse the message for `HTTP NNN` — our internal client wraps
-    // fetch failures as `POST /videos failed: HTTP 400 — <detail>`.
     if (err instanceof Error) {
         const m = err.message.match(/\bHTTP (\d{3})\b/);
         if (m)
@@ -63,30 +55,13 @@ function extractMessage(err) {
         return err;
     return 'unknown error';
 }
-/**
- * Classify a caught error from `openai.*` or a raw `fetch` to the
- * OpenRouter REST API into the closed `ErrorCode` set.
- *
- * Matching strategy:
- *   1. HTTP status first (when available).
- *   2. Message heuristics for common OpenRouter strings (credits, ZDR,
- *      "model does not exist", content policy, etc.).
- *   3. Default to INTERNAL to avoid leaking raw shapes.
- *
- * When the error carries a `Retry-After` header (on 429 / 503) we populate
- * `_meta.retry_after_seconds` so agents can back off intelligently. We
- * also attach canonical `suggestions[]` for common cases.
- */
+/** Classify upstream errors into the closed `ErrorCode` set. */
 export function classifyUpstreamError(err, contextMessage) {
     const rawMsg = extractMessage(err);
     const status = extractStatus(err);
     const lower = rawMsg.toLowerCase();
-    // Prefix every user-visible message with the handler context when the
-    // caller supplied one (e.g. `rerank`, `generate_video.submit`). Makes
-    // server-side triage possible without digging through logs.
     const fullMsg = contextMessage ? `${contextMessage}: ${rawMsg}` : rawMsg;
     const retryAfterSeconds = extractRetryAfterSeconds(err);
-    // Explicit credit / balance signals.
     if (lower.includes('insufficient balance') ||
         lower.includes('insufficient credits') ||
         lower.includes('requires more credits') ||
@@ -99,7 +74,6 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    // Zero Data Retention.
     if (lower.includes('zdr') || lower.includes('zero data retention')) {
         return toolError(ErrorCode.ZDR_INCOMPATIBLE, fullMsg, { status }, {
             suggestions: [
@@ -108,7 +82,6 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    // Model lookup failures.
     if (lower.includes('model') &&
         (lower.includes('does not exist') ||
             lower.includes('not found') ||
@@ -120,7 +93,6 @@ export function classifyUpstreamError(err, contextMessage) {
             ],
         });
     }
-    // Content policy / moderation — surface as UPSTREAM_REFUSED so callers can distinguish from 5xx.
     if (lower.includes('content policy') ||
         lower.includes('moderation') ||
         lower.includes('refused')) {
@@ -128,7 +100,6 @@ export function classifyUpstreamError(err, contextMessage) {
             suggestions: ['Rephrase the prompt', 'Try a different provider via provider.order'],
         });
     }
-    // Rate-limit specific.
     if (status === 429 || lower.includes('rate limit')) {
         return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' }, {
             suggestions: [
@@ -140,7 +111,6 @@ export function classifyUpstreamError(err, contextMessage) {
             retry_after_seconds: retryAfterSeconds,
         });
     }
-    // Timeouts (AbortError from `AbortSignal.timeout`).
     if (lower.includes('timed out') ||
         lower.includes('timeout') ||
         lower.includes('aborted') ||
@@ -149,11 +119,9 @@ export function classifyUpstreamError(err, contextMessage) {
             suggestions: ['Retry', 'Raise max_wait_ms or max_tokens'],
         });
     }
-    // Anything in the 4xx band that isn't covered above — user supplied a bad request.
     if (typeof status === 'number' && status >= 400 && status < 500) {
         return toolError(ErrorCode.INVALID_INPUT, fullMsg, { status });
     }
-    // 5xx / network errors.
     if (typeof status === 'number' && status >= 500) {
         return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg, { status }, {
             suggestions: ['Retry after a brief delay', 'Check https://status.openrouter.ai'],

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

@@ -1,22 +1,23 @@
+import { type ToolErrorResult } from '../errors.js';
 export declare class UnsafeOutputPathError extends Error {
     constructor(message: string);
 }
 /**
- * Resolve and validate a caller-supplied output path. Creates the parent
- * directory if needed. Returns the absolute path that is safe to write.
- *
- * Throws `UnsafeOutputPathError` when the resolved path escapes the root
- * (traversal attempt) and the sandbox is enabled.
+ * Resolve and validate a caller-supplied output path.
+ * Throws `UnsafeOutputPathError` on traversal attempts.
  */
 export declare function resolveSafeOutputPath(savePath: string): Promise<string>;
+/** Resolve and validate a caller-supplied input path (read-only, no mkdir). */
+export declare function resolveSafeInputPath(inputPath: string): Promise<string>;
+export type OptionalOutputPath = {
+    path: string | null;
+};
+export declare function isToolErrorResult(result: OptionalOutputPath | ToolErrorResult): result is ToolErrorResult;
+/** Resolve optional save_path; returns a tool error result on sandbox violation. */
+export declare function resolveOptionalOutputPath(savePath: string | undefined): Promise<OptionalOutputPath | ToolErrorResult>;
+export declare function isValidJobId(jobId: string): boolean;
 /**
- * Resolve and validate a caller-supplied INPUT path. Unlike
- * `resolveSafeOutputPath`, this never creates directories — it only
- * confirms the path lives inside the input sandbox and returns the
- * absolute path the caller can `fs.readFile` from.
- *
- * Accepts the same `OPENROUTER_ALLOW_UNSAFE_PATHS=1` legacy bypass.
- * Throws `UnsafeOutputPathError` on traversal attempts (re-used type so
- * handlers map errors uniformly to `ErrorCode.UNSAFE_PATH`).
+ * Resolve async-chat job status.json under OPENROUTER_OUTPUT_DIR/openrouter-jobs/.
+ * Uses realpath when the job directory exists to block symlink escapes.
  */
-export declare function resolveSafeInputPath(inputPath: string): Promise<string>;
+export declare function resolveSafeJobStatusPath(jobsDir: string, jobId: string): Promise<string | null>;

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

@@ -1,34 +1,23 @@
-/**
- * Output-path sandbox. Tools that write files (`generate_image`,
- * `generate_audio`, future `generate_video`) route their `save_path`
- * through `resolveSafeOutputPath` so an untrusted MCP caller cannot
- * traverse outside the configured output root.
- *
- * Root resolution order:
- *   1. `OPENROUTER_OUTPUT_DIR` env var (if set and non-empty).
- *   2. `process.cwd()`.
- *
- * Set `OPENROUTER_ALLOW_UNSAFE_PATHS=1` to disable the sandbox entirely
- * (legacy v2 behavior). This is discouraged — document the trade-off
- * where it appears in user configs.
- */
 import path from 'node:path';
 import { promises as fs } from 'node:fs';
 import os from 'node:os';
+import { ErrorCode, toolErrorFrom } from '../errors.js';
 /**
- * Resolve the output root directory. On Windows, `process.cwd()` can be
- * a system directory (e.g. `C:\Windows\System32`) when spawned by MCP
- * clients without a working directory override. We detect that case and
- * fall back to a writable temp directory to avoid EPERM errors.
+ * Path sandboxes for MCP caller-supplied input/output paths.
+ * Set `OPENROUTER_ALLOW_UNSAFE_PATHS=1` to disable (legacy v2 behavior).
+ *
+ * Output paths: walk to the first existing ancestor, realpath it, and reject
+ * escapes before mkdir. Re-realpath the parent after mkdir to catch symlink traversal.
+ *
+ * Input paths: realpath when the file exists; otherwise reject via resolved prefix
+ * so `../escape` fails without leaking ENOENT.
  */
+/** Output root: OPENROUTER_OUTPUT_DIR, or cwd (with Windows system-dir fallback). */
 function getOutputRoot() {
     const override = process.env.OPENROUTER_OUTPUT_DIR;
     if (override && override.length > 0)
         return path.resolve(override);
     const cwd = process.cwd();
-    // On Windows, avoid using system directories as the default output root.
-    // Common non-writable defaults when MCP clients spawn without a cwd:
-    //   C:\Windows\System32, C:\Windows, C:\Program Files\...
     if (process.platform === 'win32') {
         const cwdLower = cwd.toLowerCase().replace(/\\/g, '/');
         if (cwdLower.startsWith('c:/windows') ||
@@ -51,11 +40,8 @@ export class UnsafeOutputPathError extends Error {
     }
 }
 /**
- * Resolve and validate a caller-supplied output path. Creates the parent
- * directory if needed. Returns the absolute path that is safe to write.
- *
- * Throws `UnsafeOutputPathError` when the resolved path escapes the root
- * (traversal attempt) and the sandbox is enabled.
+ * Resolve and validate a caller-supplied output path.
+ * Throws `UnsafeOutputPathError` on traversal attempts.
  */
 export async function resolveSafeOutputPath(savePath) {
     if (isUnsafeMode()) {
@@ -65,26 +51,18 @@ export async function resolveSafeOutputPath(savePath) {
     }
     const root = getOutputRoot();
     const rootReal = await fs.realpath(root).catch(() => path.resolve(root));
-    // Resolve relative paths against the real root; absolute paths stay as
-    // given so we can check them against the root prefix below.
     const candidate = path.isAbsolute(savePath)
         ? path.resolve(savePath)
         : path.resolve(rootReal, savePath);
-    // Walk up from the candidate dir to find the first component that exists
-    // so we can realpath it. This lets us create new subdirectories under the
-    // root while still catching symlink-based traversal.
     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);
-    // The realpath of the first-existing ancestor MUST be within the root.
     if (!(ancestorReal === rootReal || ancestorReal.startsWith(withSep))) {
         throw new UnsafeOutputPathError(`save_path resolves outside OPENROUTER_OUTPUT_DIR (${rootReal}). ` +
             `Set OPENROUTER_OUTPUT_DIR to a wider root or OPENROUTER_ALLOW_UNSAFE_PATHS=1 to disable this check.`);
     }
-    // Safe to create missing intermediate directories now.
     await fs.mkdir(candidateDir, { recursive: true });
-    // Re-realpath the final parent in case mkdir traversed a symlink.
     const parentReal = await fs.realpath(candidateDir);
     if (!(parentReal === rootReal || parentReal.startsWith(withSep))) {
         throw new UnsafeOutputPathError(`save_path escapes OPENROUTER_OUTPUT_DIR via symlink (${rootReal}).`);
@@ -106,11 +84,7 @@ async function findExistingAncestor(dir) {
         }
     }
 }
-/**
- * Root-resolution for caller-supplied INPUT paths. Prefers
- * `OPENROUTER_INPUT_DIR`, then `OPENROUTER_OUTPUT_DIR`, then `process.cwd()`.
- * On Windows, applies the same system-directory detection as getOutputRoot.
- */
+/** Input root: OPENROUTER_INPUT_DIR, then OPENROUTER_OUTPUT_DIR, then cwd. */
 function getInputRoot() {
     const inputDir = process.env.OPENROUTER_INPUT_DIR;
     if (inputDir && inputDir.length > 0)
@@ -129,16 +103,7 @@ function getInputRoot() {
     }
     return cwd;
 }
-/**
- * Resolve and validate a caller-supplied INPUT path. Unlike
- * `resolveSafeOutputPath`, this never creates directories — it only
- * confirms the path lives inside the input sandbox and returns the
- * absolute path the caller can `fs.readFile` from.
- *
- * Accepts the same `OPENROUTER_ALLOW_UNSAFE_PATHS=1` legacy bypass.
- * Throws `UnsafeOutputPathError` on traversal attempts (re-used type so
- * handlers map errors uniformly to `ErrorCode.UNSAFE_PATH`).
- */
+/** Resolve and validate a caller-supplied input path (read-only, no mkdir). */
 export async function resolveSafeInputPath(inputPath) {
     if (isUnsafeMode()) {
         return path.resolve(inputPath);
@@ -149,12 +114,6 @@ export async function resolveSafeInputPath(inputPath) {
     const abs = path.isAbsolute(inputPath)
         ? path.resolve(inputPath)
         : path.resolve(rootReal, inputPath);
-    // Prefer realpath for the prefix check so callers can pass paths
-    // through symlinks (e.g. macOS `/var/...` → `/private/var/...`)
-    // without us rejecting them. If the file doesn't exist yet, fall
-    // back to a textual check on the resolved path so traversal
-    // (`../escape.png`) is still rejected with the right error type
-    // instead of leaking an ENOENT to the caller.
     let canonical;
     try {
         canonical = await fs.realpath(abs);
@@ -167,3 +126,50 @@ export async function resolveSafeInputPath(inputPath) {
     }
     return abs;
 }
+export function isToolErrorResult(result) {
+    return 'isError' in result;
+}
+/** Resolve optional save_path; returns a tool error result on sandbox violation. */
+export async function resolveOptionalOutputPath(savePath) {
+    if (!savePath)
+        return { path: null };
+    try {
+        return { path: await resolveSafeOutputPath(savePath) };
+    }
+    catch (err) {
+        if (err instanceof UnsafeOutputPathError)
+            return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
+        return toolErrorFrom(ErrorCode.INTERNAL, err);
+    }
+}
+const JOB_ID_PATTERN = /^chat_[a-zA-Z0-9_-]{1,128}$/;
+export function isValidJobId(jobId) {
+    if (!JOB_ID_PATTERN.test(jobId))
+        return false;
+    if (jobId.includes('..') || jobId.includes('/') || jobId.includes('\\'))
+        return false;
+    return true;
+}
+/**
+ * Resolve async-chat job status.json under OPENROUTER_OUTPUT_DIR/openrouter-jobs/.
+ * Uses realpath when the job directory exists to block symlink escapes.
+ */
+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)))
+            return null;
+        return path.join(jobDirCandidate, 'status.json');
+    }
+    if (!(jobDirReal === rootReal || jobDirReal.startsWith(withSep)))
+        return null;
+    return path.join(jobDirReal, 'status.json');
+}

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

@@ -0,0 +1,2 @@
+/** Strip existing extension (if any) and append a new one. */
+export declare function replaceExtension(filePath: string, newExt: string): string;

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

@@ -0,0 +1,7 @@
+import { extname } from 'node:path';
+/** 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}`;
+}

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

@@ -1,12 +1,3 @@
-/**
- * OpenRouter provider routing. Merges caller-supplied `provider` args on
- * top of env-var defaults and emits the `provider` object that goes into
- * `POST /chat/completions`. See
- * https://openrouter.ai/docs/features/provider-routing for the spec.
- *
- * Precedence: explicit tool arg > env var > unset. Empty arrays / empty
- * objects are dropped so we don't send noise to the API.
- */
 export type ProviderSort = 'price' | 'throughput' | 'latency';
 export type DataCollectionPolicy = 'allow' | 'deny';
 export interface ProviderRoutingOptions {

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

@@ -1,11 +1,5 @@
 /**
- * OpenRouter provider routing. Merges caller-supplied `provider` args on
- * top of env-var defaults and emits the `provider` object that goes into
- * `POST /chat/completions`. See
- * https://openrouter.ai/docs/features/provider-routing for the spec.
- *
- * Precedence: explicit tool arg > env var > unset. Empty arrays / empty
- * objects are dropped so we don't send noise to the API.
+ * OpenRouter provider routing — merges tool args over OPENROUTER_PROVIDER_* env defaults.
  */
 import { logger } from '../logger.js';
 function parseCsv(raw) {
@@ -21,9 +15,6 @@ function parseJsonArray(raw, name) {
     if (!raw)
         return undefined;
     const trimmed = raw.trim();
-    // If the value looks like a JSON array (`[...]`), require it to BE valid JSON.
-    // Otherwise fall back to CSV parsing — that way `a,b,c` works too, but a
-    // malformed `[bogus]` doesn't silently become a single-element string array.
     if (trimmed.startsWith('[')) {
         try {
             const parsed = JSON.parse(trimmed);
@@ -84,10 +75,6 @@ export function readProviderDefaults() {
             out.order = order;
     }
     catch (err) {
-        // Don't crash the server on a malformed env var — log once so an
-        // operator notices instead of wondering why their ordering is being
-        // ignored. All other OPENROUTER_PROVIDER_* fields follow the same
-        // "silent drop" policy for consistency.
         logger.warn('OPENROUTER_PROVIDER_ORDER ignored', {
             err: err instanceof Error ? err.message : String(err),
         });

package/dist/tool-handlers/rerank.js

@@ -26,8 +26,6 @@ export async function handleRerankDocuments(request, apiClient) {
     catch (err) {
         return classifyUpstreamError(err, 'rerank');
     }
-    // Normalize to a stable shape: always expose `score` (OpenRouter
-    // providers sometimes return `relevance_score`, sometimes `score`).
     const normalized = (response.results ?? []).map((r) => {
         const score = typeof r.score === 'number' ? r.score : r.relevance_score;
         const out = { index: r.index, score };

package/dist/tool-handlers/search-models.d.ts

@@ -9,12 +9,6 @@ export interface SearchModelsArgs {
         video?: boolean;
     };
     limit?: number;
-    /**
-     * Skip this many matching results before returning `limit`. Paired with
-     * `limit` and the returned `next_offset` to let large model lists be
-     * paged safely. Follows Phil Schmid's "paginate large results" best
-     * practice.
-     */
     offset?: number;
 }
 export declare function handleSearchModels(request: {

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

@@ -1,14 +1,8 @@
-/**
- * speech_to_text — uses OpenRouter's dedicated POST /api/v1/audio/transcriptions
- * endpoint (launched May 2026) for speech-to-text transcription. Faster and more
- * cost-efficient than routing through chat completions for pure transcription.
- *
- * Supported models: OpenAI Whisper-1, GPT-4o Transcribe, GPT-4o Mini Transcribe,
- * Mistral Voxtral Mini Transcribe.
- */
-import { promises as fs } from 'fs';
+/** 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 { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
 import { SERVER_VERSION } from '../version.js';
 import { logger } from '../logger.js';
@@ -40,26 +34,17 @@ function audioFormatFromExt(ext) {
             return 'mp3';
     }
 }
-/**
- * Resolve audio input to base64 + format, supporting:
- * - data: URLs (pass through)
- * - http(s) URLs (fetch)
- * - local file paths (sandboxed read)
- */
 async function resolveAudioInput(audioPath) {
     const trimmed = audioPath.trim();
     if (!trimmed)
         throw new Error('audio_path is empty');
-    // Data URL
     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] };
     }
-    // HTTP URL
     if (/^https?:\/\//i.test(trimmed)) {
-        const { fetchHttpResource } = await import('./fetch-utils.js');
         const { buffer, contentType } = await fetchHttpResource(trimmed, {
             timeoutMs: 60_000,
             maxBytes: 100 * 1024 * 1024,
@@ -68,7 +53,6 @@ async function resolveAudioInput(audioPath) {
         const format = contentType?.match(/audio\/(\w+)/)?.[1] || 'mp3';
         return { data: buffer.toString('base64'), format };
     }
-    // Local file
     const abs = await resolveSafeInputPath(trimmed);
     const buf = await fs.readFile(abs);
     const ext = path.extname(abs);
@@ -90,7 +74,6 @@ export async function handleSpeechToText(request, apiClient) {
         language,
         response_format,
     });
-    // Resolve audio input
     let audioInput;
     try {
         audioInput = await resolveAudioInput(audio_path);
@@ -103,7 +86,6 @@ export async function handleSpeechToText(request, apiClient) {
             return toolErrorFrom(ErrorCode.UPSTREAM_REFUSED, err);
         return toolErrorFrom(ErrorCode.INVALID_INPUT, err);
     }
-    // Build request body
     const body = {
         model: model || DEFAULT_MODEL,
         input_audio: {

package/dist/tool-handlers/structured-output.d.ts

@@ -6,10 +6,7 @@ export interface StructuredResult<T = unknown> {
     structuredContent: T;
     _meta: Record<string, unknown>;
 }
-/**
- * Wrap a JSON-serializable object in the MCP-spec dual-representation
- * format. `meta` is merged on top of the default `server_version` stamp.
- */
+/** Wrap JSON-serializable data in MCP dual-representation format. */
 export declare function buildStructuredResult<T>(data: T, meta?: Record<string, unknown>): StructuredResult<T>;
 /** Read typed JSON from an MCP tool result (structuredContent or legacy text). */
 export declare function readToolPayload<T = unknown>(result: {

package/dist/tool-handlers/structured-output.js

@@ -1,20 +1,6 @@
-/**
- * Helper for building MCP tool responses that carry structured data
- * alongside the legacy text representation.
- *
- * Per MCP spec 2025-06-18 §5.2.6-7, when a tool has an `outputSchema`
- * the response SHOULD include `structuredContent` (the typed object)
- * AND, for backwards compatibility with clients that don't parse that
- * field, `content` with a serialized JSON text block.
- *
- * Consumers use `buildStructuredResult(data, meta?)` and get back the
- * full `{ content, structuredContent, _meta }` shape.
- */
+/** Build MCP tool responses with `structuredContent` plus legacy JSON text. */
 import { SERVER_VERSION } from '../version.js';
-/**
- * Wrap a JSON-serializable object in the MCP-spec dual-representation
- * format. `meta` is merged on top of the default `server_version` stamp.
- */
+/** Wrap JSON-serializable data in MCP dual-representation format. */
 export function buildStructuredResult(data, meta = {}) {
     return {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],

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

@@ -14,16 +14,6 @@ export declare function handleTextToSpeech(request: {
         arguments: TextToSpeechRequest;
     };
 }, apiClient: OpenRouterAPIClient): Promise<import("../errors.js").ToolErrorResult | {
-    content: ({
-        type: "text";
-        text: string;
-        mimeType?: undefined;
-        data?: undefined;
-    } | {
-        type: "audio";
-        mimeType: string;
-        data: string;
-        text?: undefined;
-    })[];
+    content: import("./tool-result-payload.js").BinaryToolContent[];
     _meta: Record<string, unknown>;
 }>;

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

@@ -1,18 +1,13 @@
-/**
- * text_to_speech — uses OpenRouter's dedicated POST /api/v1/audio/speech
- * endpoint (launched May 2026) for text-to-speech. Faster and more cost-efficient
- * than routing through chat completions with audio modality.
- *
- * Supported providers: OpenAI (GPT-4o Mini TTS), Google (Gemini Flash TTS),
- * Mistral (Voxtral Mini TTS).
- */
-import { promises as fs } from 'fs';
-import { extname } from 'path';
-import { resolveSafeOutputPath, UnsafeOutputPathError } from './path-safety.js';
+/** Dedicated POST /api/v1/audio/speech — OpenAI, Gemini Flash TTS, Voxtral. */
+import { promises as fs } from 'node:fs';
+import { extname } from 'node:path';
+import { resolveOptionalOutputPath, isToolErrorResult } from './path-safety.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 { buildBinaryToolResult } from './tool-result-payload.js';
+import { replaceExtension } from './path-utils.js';
 import { buildCacheHeaders } from './cache.js';
 const DEFAULT_MODEL = 'openai/gpt-4o-mini-tts-2025-12-15';
 const DEFAULT_VOICE = 'alloy';
@@ -33,19 +28,10 @@ export async function handleTextToSpeech(request, apiClient) {
         input_preview: input.slice(0, 80),
         save_path: save_path ? 'provided' : 'none',
     });
-    // Resolve save path early
-    let safeSavePath = null;
-    if (save_path) {
-        try {
-            safeSavePath = await resolveSafeOutputPath(save_path);
-        }
-        catch (err) {
-            if (err instanceof UnsafeOutputPathError)
-                return toolErrorFrom(ErrorCode.UNSAFE_PATH, err);
-            return toolErrorFrom(ErrorCode.INTERNAL, err);
-        }
-    }
-    // Build request body
+    const savePathResult = await resolveOptionalOutputPath(save_path);
+    if (isToolErrorResult(savePathResult))
+        return savePathResult;
+    const safeSavePath = savePathResult.path;
     const body = {
         model: model || DEFAULT_MODEL,
         input,
@@ -67,7 +53,6 @@ export async function handleTextToSpeech(request, apiClient) {
     }
     const { buffer, contentType } = result;
     const mimeType = contentType.split(';')[0]?.trim() || 'audio/mpeg';
-    // Determine file extension from format
     const ext = response_format || 'mp3';
     const baseMeta = {
         server_version: SERVER_VERSION,
@@ -77,9 +62,8 @@ export async function handleTextToSpeech(request, apiClient) {
         voice: voice || DEFAULT_VOICE,
     };
     if (safeSavePath) {
-        // Ensure extension matches
         const currentExt = extname(safeSavePath).toLowerCase().slice(1);
-        const actualPath = currentExt === ext ? safeSavePath : `${safeSavePath}.${ext}`;
+        const actualPath = currentExt === ext ? safeSavePath : replaceExtension(safeSavePath, ext);
         try {
             await fs.writeFile(actualPath, buffer);
         }
@@ -87,19 +71,14 @@ export async function handleTextToSpeech(request, apiClient) {
             return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
         }
         baseMeta.save_path = actualPath;
-        return {
-            content: [
-                { type: 'text', text: `Speech saved to: ${actualPath}` },
-                { type: 'audio', mimeType, data: buffer.toString('base64') },
-            ],
-            _meta: baseMeta,
-        };
+        return buildBinaryToolResult({ kind: 'audio', buffer, mimeType }, {
+            savedPath: actualPath,
+            summaryText: `Speech saved to: ${actualPath}`,
+            meta: baseMeta,
+        });
     }
-    return {
-        content: [
-            { type: 'text', text: `Speech generated (${buffer.length} bytes, ${mimeType}).` },
-            { type: 'audio', mimeType, data: buffer.toString('base64') },
-        ],
-        _meta: baseMeta,
-    };
+    return buildBinaryToolResult({ kind: 'audio', buffer, mimeType }, {
+        prefixText: `Speech generated (${buffer.length} bytes, ${mimeType}).`,
+        meta: baseMeta,
+    });
 }