@stabgan/openrouter-mcp-multimodal 4.6.1 → 4.7.0

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

@@ -1,27 +1,11 @@
 /**
- * User-Agent we send on outbound fetches from `fetchHttpResource`. Some
- * CDNs/WAFs (notably Wikimedia/Varnish) reject requests without a UA, so
- * we identify ourselves with the package name + current version + a repo
- * URL so origin operators can contact us if our traffic misbehaves.
- *
- * Version is read from package.json at module load so version bumps don't
- * require hand-edits here. Falls back to `dev` if package.json can't be
- * located (e.g. in certain bundled environments).
+ * User-Agent for outbound fetches — some CDNs reject requests without one.
  */
 export declare const FETCH_USER_AGENT: string;
 export declare function readEnvInt(name: string, fallback: number, min?: number): number;
 /** Blocks RFC1918, loopback, link-local, CGNAT, metadata. */
 export declare function isBlockedIPv4(ip: string): boolean;
-/**
- * Comprehensive IPv6 SSRF block list. Covers loopback, unspecified,
- * IPv4-mapped, IPv4-compatible, link-local, site-local, ULA, multicast,
- * discard, documentation, Teredo, 6to4 (re-validates the embedded IPv4
- * against `isBlockedIPv4`), and ORCHID. Returns `true` for any input that
- * is a valid IPv6 literal in a reserved or private range.
- *
- * For non-IPv6 input returns `false` (the caller is expected to also run
- * `isBlockedIPv4` for IPv4 input).
- */
+/** SSRF block list for IPv6 literals (private/reserved ranges). */
 export declare function isBlockedIPv6(ip: string): boolean;
 /** Resolve hostname and ensure the resolved address is not private/link-local. */
 export declare function assertUrlSafeForFetch(urlString: string): Promise<URL>;

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

@@ -8,21 +8,12 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 /**
- * User-Agent we send on outbound fetches from `fetchHttpResource`. Some
- * CDNs/WAFs (notably Wikimedia/Varnish) reject requests without a UA, so
- * we identify ourselves with the package name + current version + a repo
- * URL so origin operators can contact us if our traffic misbehaves.
- *
- * Version is read from package.json at module load so version bumps don't
- * require hand-edits here. Falls back to `dev` if package.json can't be
- * located (e.g. in certain bundled environments).
+ * User-Agent for outbound fetches — some CDNs reject requests without one.
  */
 export const FETCH_USER_AGENT = (() => {
     const fallback = 'openrouter-mcp-multimodal/dev (+https://github.com/stabgan/openrouter-mcp-multimodal)';
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
-        // Walk up a few levels looking for package.json (handles both
-        // dist/tool-handlers/… and src/tool-handlers/… layouts).
         for (let hop = 0; hop < 5; hop++) {
             const candidate = path.resolve(here, '../'.repeat(hop), 'package.json');
             try {
@@ -75,22 +66,13 @@ export function isBlockedIPv4(ip) {
         return true;
     return false;
 }
-/**
- * Expand an IPv6 literal to eight 16-bit groups as lowercase hex without
- * separators. Accepts compressed forms (::), zone ids (%eth0), and IPv4-mapped
- * / IPv4-compatible tails. Returns null if the input is not a valid IPv6
- * literal.
- */
+/** Expand an IPv6 literal to eight 16-bit groups, or null if invalid. */
 function expandIPv6(ip) {
-    // Strip optional brackets (URL host form) and zone id before validation.
     const noZone = ip.includes('%') ? ip.split('%')[0] : ip;
     const noBrackets = noZone.replace(/^\[|\]$/g, '');
     if (!net.isIPv6(noBrackets))
         return null;
     let addr = noBrackets.toLowerCase();
-    // Pull out any IPv4 tail (`::ffff:a.b.c.d`, `::a.b.c.d`, `x:y::a.b.c.d`)
-    // and substitute two 16-bit zero groups in its place. This way the rest
-    // of the parser only needs to handle pure-hex 8-group form.
     let v4Tail = null;
     const dotIndex = addr.indexOf('.');
     if (dotIndex >= 0) {
@@ -103,12 +85,10 @@ function expandIPv6(ip) {
             return null;
         }
         v4Tail = [((parts[0] << 8) | parts[1]) & 0xffff, ((parts[2] << 8) | parts[3]) & 0xffff];
-        // Substitute "g6:g7" in hex. E.g. "::ffff:127.0.0.1" -> "::ffff:7f00:0001"
         const hex6 = v4Tail[0].toString(16);
         const hex7 = v4Tail[1].toString(16);
         addr = addr.slice(0, lastColon) + ':' + hex6 + ':' + hex7;
     }
-    // Split on "::" at most once; fill the gap with zero groups.
     const halves = addr.split('::');
     if (halves.length > 2)
         return null;
@@ -135,22 +115,12 @@ function expandIPv6(ip) {
     }
     return out.length === 8 ? out : null;
 }
-/**
- * Comprehensive IPv6 SSRF block list. Covers loopback, unspecified,
- * IPv4-mapped, IPv4-compatible, link-local, site-local, ULA, multicast,
- * discard, documentation, Teredo, 6to4 (re-validates the embedded IPv4
- * against `isBlockedIPv4`), and ORCHID. Returns `true` for any input that
- * is a valid IPv6 literal in a reserved or private range.
- *
- * For non-IPv6 input returns `false` (the caller is expected to also run
- * `isBlockedIPv4` for IPv4 input).
- */
+/** SSRF block list for IPv6 literals (private/reserved ranges). */
 export function isBlockedIPv6(ip) {
     const groups = expandIPv6(ip);
     if (!groups)
         return false;
     const [g0, g1, g2, g3, g4, g5, g6, g7] = groups;
-    // ::  (unspecified)
     if (g0 === 0 &&
         g1 === 0 &&
         g2 === 0 &&
@@ -161,7 +131,6 @@ export function isBlockedIPv6(ip) {
         g7 === 0) {
         return true;
     }
-    // ::1 (loopback)
     if (g0 === 0 &&
         g1 === 0 &&
         g2 === 0 &&
@@ -172,49 +141,36 @@ export function isBlockedIPv6(ip) {
         g7 === 1) {
         return true;
     }
-    // ::ffff:0:0/96 — IPv4-mapped. Re-check the embedded IPv4.
     if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0xffff) {
         const v4 = ((g6 << 16) >>> 0) | g7;
         const dotted = `${(v4 >>> 24) & 0xff}.${(v4 >>> 16) & 0xff}.${(v4 >>> 8) & 0xff}.${v4 & 0xff}`;
         return isBlockedIPv4(dotted);
     }
-    // ::/96 IPv4-compatible (deprecated but still routable in places).
     if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0) {
-        // Only treat as IPv4-compat if g6/g7 actually look like an IPv4 (both
-        // are nonzero or this is the all-zeros case handled above).
         if (g6 !== 0 || g7 !== 0) {
             const v4 = ((g6 << 16) >>> 0) | g7;
             const dotted = `${(v4 >>> 24) & 0xff}.${(v4 >>> 16) & 0xff}.${(v4 >>> 8) & 0xff}.${v4 & 0xff}`;
             return isBlockedIPv4(dotted);
         }
     }
-    // fc00::/7 — ULA
     if ((g0 & 0xfe00) === 0xfc00)
         return true;
-    // fe80::/10 — link-local
     if ((g0 & 0xffc0) === 0xfe80)
         return true;
-    // fec0::/10 — deprecated site-local
     if ((g0 & 0xffc0) === 0xfec0)
         return true;
-    // ff00::/8 — multicast (all forms)
     if ((g0 & 0xff00) === 0xff00)
         return true;
-    // 100::/64 — discard prefix (RFC 6666)
     if (g0 === 0x0100 && g1 === 0 && g2 === 0 && g3 === 0)
         return true;
-    // 2001:db8::/32 — documentation
     if (g0 === 0x2001 && g1 === 0x0db8)
         return true;
-    // 2001::/32 — Teredo
     if (g0 === 0x2001 && g1 === 0x0000)
         return true;
-    // 2001:10::/28, 2001:20::/28 — ORCHID / deprecated
     if (g0 === 0x2001 && (g1 & 0xfff0) === 0x0010)
         return true;
     if (g0 === 0x2001 && (g1 & 0xfff0) === 0x0020)
         return true;
-    // 2002::/16 — 6to4; re-check embedded IPv4 for private/reserved use.
     if (g0 === 0x2002) {
         const v4 = ((g1 << 16) >>> 0) | g2;
         const dotted = `${(v4 >>> 24) & 0xff}.${(v4 >>> 16) & 0xff}.${(v4 >>> 8) & 0xff}.${v4 & 0xff}`;
@@ -351,10 +307,6 @@ export async function fetchHttpResource(urlString, opts) {
                 redirect: 'manual',
                 signal: controller.signal,
                 headers: {
-                    // Some CDNs/WAFs (notably Wikimedia/Varnish) reject requests
-                    // without a User-Agent with HTTP 400. Identify ourselves so
-                    // analyze_image / analyze_audio / analyze_video work against
-                    // those origins. See https://github.com/stabgan/openrouter-mcp-multimodal/issues/13
                     'User-Agent': FETCH_USER_AGENT,
                     Accept: 'image/*, audio/*, video/*, */*;q=0.8',
                 },

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

@@ -22,46 +22,12 @@ export declare function detectAudioFormat(data: Buffer): {
     mimeType: string;
 };
 export declare function wrapPcmInWav(pcmData: Buffer, sampleRate?: number): Buffer;
-/** Strip existing extension (if any) and append a new one. */
-export declare function replaceExtension(filePath: string, newExt: string): string;
+export { replaceExtension } from './path-utils.js';
 export declare function handleGenerateAudio(request: {
     params: {
         arguments: GenerateAudioToolRequest;
     };
 }, openai: OpenAI): Promise<import("../errors.js").ToolErrorResult | {
-    content: ({
-        type: "text";
-        text: string;
-        mimeType?: undefined;
-        data?: undefined;
-    } | {
-        type: "audio";
-        mimeType: string;
-        data: string;
-        text?: undefined;
-    })[];
-    _meta: {
-        server_version: string;
-        save_path: string;
-        mime: string;
-        size_bytes: number;
-    };
-} | {
-    content: ({
-        type: "text";
-        text: string;
-        mimeType?: undefined;
-        data?: undefined;
-    } | {
-        type: "audio";
-        mimeType: string;
-        data: string;
-        text?: undefined;
-    })[];
-    _meta: {
-        server_version: string;
-        mime: string;
-        size_bytes: number;
-        save_path?: undefined;
-    };
+    content: import("./tool-result-payload.js").BinaryToolContent[];
+    _meta: Record<string, unknown>;
 }>;

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

@@ -1,10 +1,13 @@
-import { promises as fs } from 'fs';
-import { extname } from 'path';
-import { resolveSafeOutputPath, UnsafeOutputPathError } from './path-safety.js';
-import { ErrorCode, toolError, toolErrorFrom } from '../errors.js';
+import { promises as fs } from 'node:fs';
+import { extname } from 'node:path';
+import { resolveOptionalOutputPath, isToolErrorResult } from './path-safety.js';
+import { asOpenAIChatBody } from './chat-request.js';
+import { ErrorCode, toolError } 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';
 const DEFAULT_MODEL = 'openai/gpt-audio';
 const DEFAULT_VOICE = 'alloy';
 const DEFAULT_FORMAT = 'pcm16';
@@ -78,12 +81,7 @@ export function detectAudioFormat(data) {
 export function wrapPcmInWav(pcmData, sampleRate = DEFAULT_PCM_SAMPLE_RATE) {
     return Buffer.concat([createWavHeader(pcmData.length, sampleRate), pcmData]);
 }
-/** 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}`;
-}
+export { replaceExtension } from './path-utils.js';
 export async function handleGenerateAudio(request, openai) {
     const { prompt, model, voice, format, save_path } = request.params.arguments ?? {
         prompt: '',
@@ -91,7 +89,6 @@ export async function handleGenerateAudio(request, openai) {
     if (!prompt?.trim()) {
         return toolError(ErrorCode.INVALID_INPUT, 'prompt is required.');
     }
-    // Audit entry. See generate_image for rationale.
     logger.audit('generate_audio.start', {
         model: model || DEFAULT_MODEL,
         voice: voice?.trim() || DEFAULT_VOICE,
@@ -99,32 +96,23 @@ export async function handleGenerateAudio(request, openai) {
         prompt_preview: prompt.slice(0, 80),
         save_path: save_path ? 'provided' : 'none',
     });
-    // Fail-fast on unsafe paths BEFORE spending tokens.
-    let safeBase = null;
-    if (save_path) {
-        try {
-            safeBase = await resolveSafeOutputPath(save_path);
-        }
-        catch (e) {
-            if (e instanceof UnsafeOutputPathError)
-                return toolErrorFrom(ErrorCode.UNSAFE_PATH, e);
-            return toolErrorFrom(ErrorCode.INTERNAL, e);
-        }
-    }
+    const savePathResult = await resolveOptionalOutputPath(save_path);
+    if (isToolErrorResult(savePathResult))
+        return savePathResult;
+    const safeBase = savePathResult.path;
     const selectedFormat = VALID_FORMATS.includes(format ?? '')
         ? format
         : DEFAULT_FORMAT;
     const selectedVoice = voice?.trim() || DEFAULT_VOICE;
     let stream;
     try {
-        stream = (await openai.chat.completions.create({
+        stream = (await openai.chat.completions.create(asOpenAIChatBody({
             model: model || DEFAULT_MODEL,
             messages: [{ role: 'user', content: prompt }],
             modalities: ['text', 'audio'],
             audio: { voice: selectedVoice, format: selectedFormat },
             stream: true,
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        }));
+        })));
     }
     catch (err) {
         return classifyUpstreamError(err, 'generate_audio');
@@ -152,13 +140,11 @@ export async function handleGenerateAudio(request, openai) {
         }
         let audioBuffer = Buffer.from(fullAudioBase64, 'base64');
         const detected = detectAudioFormat(audioBuffer);
-        // Always wrap raw PCM in WAV so it's playable
         if (detected.ext === 'pcm') {
             audioBuffer = Buffer.from(wrapPcmInWav(audioBuffer));
             detected.ext = 'wav';
             detected.mimeType = 'audio/wav';
         }
-        const returnBase64 = audioBuffer.toString('base64');
         if (safeBase) {
             const fileExt = extname(safeBase).toLowerCase().slice(1);
             const actualSavePath = fileExt === detected.ext ? safeBase : replaceExtension(safeBase, detected.ext);
@@ -169,30 +155,20 @@ export async function handleGenerateAudio(request, openai) {
             const result = transcript
                 ? `Audio saved to: ${actualSavePath}${formatNote}\nTranscript: ${transcript}`
                 : `Audio saved to: ${actualSavePath}${formatNote}`;
-            return {
-                content: [
-                    { type: 'text', text: result },
-                    { type: 'audio', mimeType: detected.mimeType, data: returnBase64 },
-                ],
-                _meta: {
+            return buildBinaryToolResult({ kind: 'audio', buffer: audioBuffer, mimeType: detected.mimeType }, {
+                savedPath: actualSavePath,
+                summaryText: result,
+                meta: {
                     server_version: SERVER_VERSION,
-                    save_path: actualSavePath,
-                    mime: detected.mimeType,
-                    size_bytes: audioBuffer.length,
                 },
-            };
+            });
         }
-        return {
-            content: [
-                { type: 'text', text: transcript || 'Audio generated successfully.' },
-                { type: 'audio', mimeType: detected.mimeType, data: returnBase64 },
-            ],
-            _meta: {
+        return buildBinaryToolResult({ kind: 'audio', buffer: audioBuffer, mimeType: detected.mimeType }, {
+            prefixText: transcript || 'Audio generated successfully.',
+            meta: {
                 server_version: SERVER_VERSION,
-                mime: detected.mimeType,
-                size_bytes: audioBuffer.length,
             },
-        };
+        });
     }
     catch (err) {
         return classifyUpstreamError(err, 'generate_audio (stream)');

package/dist/tool-handlers/generate-image-dedicated.d.ts

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

package/dist/tool-handlers/generate-image-dedicated.js

@@ -1,53 +1,24 @@
-/**
- * generate_image_dedicated — uses OpenRouter's dedicated POST /api/v1/images
- * endpoint (launched June 2026) for image generation. Supports normalized
- * resolution tiers, aspect ratios, quality levels, output formats, and
- * input_references for image-to-image workflows.
- *
- * This is distinct from the original `generate_image` tool which uses chat
- * completions with `modalities: ['image', 'text']`. New image models are
- * added exclusively to this dedicated endpoint.
- */
-import { promises as fs } from 'fs';
-import path from 'node:path';
-import { resolveSafeOutputPath, resolveSafeInputPath, UnsafeOutputPathError, } from './path-safety.js';
+/** Dedicated POST /api/v1/images — distinct from chat-completions `generate_image`. */
+import { promises as fs } from 'node:fs';
+import { resolveOptionalOutputPath, isToolErrorResult, UnsafeOutputPathError, } from './path-safety.js';
+import { toOpenRouterImageReference } from './image-source.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 { fetchHttpResource, readEnvInt } from './fetch-utils.js';
 import { buildCacheHeaders } from './cache.js';
 const DEFAULT_MODEL = 'google/gemini-2.5-flash-image';
 const VALID_RESOLUTIONS = new Set(['512', '0.5K', '1K', '2K', '4K']);
 const VALID_QUALITIES = new Set(['auto', 'low', 'medium', 'high']);
 const VALID_OUTPUT_FORMATS = new Set(['png', 'jpeg', 'webp', 'svg']);
-/**
- * Resolve an input image reference (local path, URL, or data URL) into the
- * OpenRouter `input_references` shape: `{ type: "image_url", image_url: { url } }`.
- */
-async function resolveReference(source) {
-    const trimmed = source.trim();
-    if (!trimmed)
-        throw new Error('Empty input_references entry');
-    // Data URLs and HTTP URLs pass through directly
-    if (trimmed.startsWith('data:') || /^https?:\/\//i.test(trimmed)) {
-        return { type: 'image_url', image_url: { url: trimmed } };
-    }
-    // Local file: sandbox, read, and convert to data URL
-    const abs = await resolveSafeInputPath(trimmed);
-    const buf = await fs.readFile(abs);
-    const ext = path.extname(abs).toLowerCase();
-    const mime = ext === '.png'
-        ? 'image/png'
-        : ext === '.webp'
-            ? 'image/webp'
-            : ext === '.gif'
-                ? 'image/gif'
-                : ext === '.svg'
-                    ? 'image/svg+xml'
-                    : 'image/jpeg';
-    const dataUrl = `data:${mime};base64,${buf.toString('base64')}`;
-    return { type: 'image_url', image_url: { url: dataUrl } };
-}
+const MIME_BY_FORMAT = {
+    png: 'image/png',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    jpeg: 'image/jpeg',
+};
 export async function handleGenerateImageDedicated(request, apiClient) {
     const args = request.params.arguments ?? {};
     const { prompt, model, resolution, aspect_ratio, quality, output_format, n, input_references, save_path, provider, cache, cache_ttl, cache_clear, } = args;
@@ -64,7 +35,6 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         input_references_count: input_references?.length ?? 0,
         save_path: save_path ? 'provided' : 'none',
     });
-    // Validate enums
     if (resolution && !VALID_RESOLUTIONS.has(resolution)) {
         return toolError(ErrorCode.INVALID_INPUT, `resolution '${resolution}' is not supported. Valid: ${[...VALID_RESOLUTIONS].join(', ')}.`);
     }
@@ -74,19 +44,10 @@ export async function handleGenerateImageDedicated(request, apiClient) {
     if (output_format && !VALID_OUTPUT_FORMATS.has(output_format)) {
         return toolError(ErrorCode.INVALID_INPUT, `output_format '${output_format}' is not supported. Valid: ${[...VALID_OUTPUT_FORMATS].join(', ')}.`);
     }
-    // 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,
         prompt,
@@ -103,10 +64,9 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         body.n = n;
     if (provider && typeof provider === 'object')
         body.provider = provider;
-    // Resolve input references
     if (input_references?.length) {
         try {
-            const refs = await Promise.all(input_references.map(resolveReference));
+            const refs = await Promise.all(input_references.map(toOpenRouterImageReference));
             body.input_references = refs;
         }
         catch (err) {
@@ -115,7 +75,6 @@ export async function handleGenerateImageDedicated(request, apiClient) {
             return toolErrorFrom(ErrorCode.INVALID_INPUT, err, 'input_references');
         }
     }
-    // Build cache headers
     const headers = buildCacheHeaders({ cache, cache_ttl, cache_clear });
     let response;
     try {
@@ -132,15 +91,7 @@ export async function handleGenerateImageDedicated(request, apiClient) {
     }
     const firstImage = images[0];
     const imageData = firstImage.b64_json;
-    const mimeType = output_format === 'png'
-        ? 'image/png'
-        : output_format === 'webp'
-            ? 'image/webp'
-            : output_format === 'svg'
-                ? 'image/svg+xml'
-                : output_format === 'jpeg'
-                    ? 'image/jpeg'
-                    : 'image/png'; // default
+    const mimeType = MIME_BY_FORMAT[output_format ?? ''] ?? 'image/png';
     const baseMeta = {
         server_version: SERVER_VERSION,
         model: model || DEFAULT_MODEL,
@@ -150,31 +101,58 @@ export async function handleGenerateImageDedicated(request, apiClient) {
         baseMeta.usage = response.usage;
     if (firstImage.revised_prompt)
         baseMeta.revised_prompt = firstImage.revised_prompt;
-    // Save to file if requested
-    if (safeSavePath && imageData) {
-        try {
-            await fs.writeFile(safeSavePath, imageData, { encoding: 'base64' });
+    if (safeSavePath) {
+        let buffer = null;
+        if (imageData) {
+            try {
+                buffer = Buffer.from(imageData, 'base64');
+                if (buffer.length === 0)
+                    buffer = null;
+            }
+            catch {
+                buffer = null;
+            }
         }
-        catch (err) {
-            return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
+        if (buffer) {
+            try {
+                await fs.writeFile(safeSavePath, buffer);
+            }
+            catch (err) {
+                return toolErrorFrom(ErrorCode.INTERNAL, err, 'Write');
+            }
+            baseMeta.save_path = safeSavePath;
+            return buildBinaryToolResult({ kind: 'image', buffer, mimeType }, {
+                savedPath: safeSavePath,
+                summaryText: `Image saved to: ${safeSavePath}`,
+                meta: baseMeta,
+            });
+        }
+        if (firstImage.url) {
+            try {
+                const maxBytes = readEnvInt('OPENROUTER_IMAGE_MAX_DOWNLOAD_BYTES', 20 * 1024 * 1024, 1024);
+                const { buffer: fetched, contentType } = await fetchHttpResource(firstImage.url, {
+                    maxBytes,
+                    maxRedirects: 3,
+                    timeoutMs: 30_000,
+                });
+                const resolvedMime = contentType?.split(';')[0]?.trim() || mimeType;
+                await fs.writeFile(safeSavePath, fetched);
+                baseMeta.save_path = safeSavePath;
+                return buildBinaryToolResult({ kind: 'image', buffer: fetched, mimeType: resolvedMime }, {
+                    savedPath: safeSavePath,
+                    summaryText: `Image saved to: ${safeSavePath}`,
+                    meta: { ...baseMeta, mime: resolvedMime, image_url: firstImage.url },
+                });
+            }
+            catch (err) {
+                return toolErrorFrom(ErrorCode.UPSTREAM_HTTP, err, 'Download image URL for save_path');
+            }
         }
-        baseMeta.save_path = safeSavePath;
-        return {
-            content: [
-                { type: 'text', text: `Image saved to: ${safeSavePath}` },
-                ...(imageData ? [{ type: 'image', mimeType, data: imageData }] : []),
-            ],
-            _meta: baseMeta,
-        };
+        return toolError(ErrorCode.UPSTREAM_REFUSED, 'Model returned no usable image data for save_path (empty b64_json and URL download unavailable).');
     }
-    // Return inline
     if (imageData) {
-        return {
-            content: [{ type: 'image', mimeType, data: imageData }],
-            _meta: baseMeta,
-        };
+        return buildBinaryToolResult({ kind: 'image', buffer: Buffer.from(imageData, 'base64'), mimeType }, { inlineOnly: true, meta: baseMeta });
     }
-    // URL-only response (some models return URLs instead of base64)
     return {
         content: [{ type: 'text', text: `Image generated. URL: ${firstImage.url}` }],
         _meta: { ...baseMeta, image_url: firstImage.url },

package/dist/tool-handlers/generate-image-input.d.ts

@@ -1,3 +1,2 @@
 import OpenAI from 'openai';
-export declare function resolveInputImage(ref: string): Promise<string>;
 export declare function buildUserContent(prompt: string, inputImages?: string[]): Promise<string | OpenAI.Chat.Completions.ChatCompletionContentPart[]>;

package/dist/tool-handlers/generate-image-input.js

@@ -1,20 +1,4 @@
-import { promises as fs } from 'fs';
-import path from 'node:path';
-import { resolveSafeInputPath } from './path-safety.js';
-import { mimeFromExtension } from './image-utils.js';
-export async function resolveInputImage(ref) {
-    const trimmed = ref.trim();
-    if (!trimmed)
-        throw new Error('empty input_images entry');
-    if (trimmed.startsWith('data:'))
-        return trimmed;
-    if (/^https?:\/\//i.test(trimmed))
-        return trimmed;
-    const abs = await resolveSafeInputPath(trimmed);
-    const buf = await fs.readFile(abs);
-    const mime = mimeFromExtension(path.extname(abs)) || 'image/png';
-    return `data:${mime};base64,${buf.toString('base64')}`;
-}
+import { resolveImageUrl } from './image-source.js';
 export async function buildUserContent(prompt, inputImages) {
     if (!inputImages?.length) {
         return `Generate an image: ${prompt}`;
@@ -27,7 +11,7 @@ export async function buildUserContent(prompt, inputImages) {
                 `closely; do not alter them.\n\nPrompt: ${prompt}`,
         },
     ];
-    const urls = await Promise.all(inputImages.map((ref) => resolveInputImage(ref)));
+    const urls = await Promise.all(inputImages.map((ref) => resolveImageUrl(ref)));
     for (const url of urls) {
         parts.push({
             type: 'image_url',