@stabgan/openrouter-mcp-multimodal 2.0.0 → 3.0.0

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

@@ -1,6 +1,6 @@
 import path from 'path';
 import { promises as fs } from 'fs';
-import { readEnvInt, isBlockedIPv4 as _isBlockedIPv4, assertUrlSafeForFetch as _assertUrlSafeForFetch, fetchHttpResource, } from './fetch-utils.js';
+import { readEnvInt, isBlockedIPv4 as _isBlockedIPv4, assertUrlSafeForFetch as _assertUrlSafeForFetch, fetchHttpResource, parseBase64DataUrl, } from './fetch-utils.js';
 // Re-export for backward compatibility (tests import from image-utils)
 export const isBlockedIPv4 = _isBlockedIPv4;
 export const assertUrlSafeForFetch = _assertUrlSafeForFetch;
@@ -66,24 +66,71 @@ export async function fetchHttpImage(urlString) {
 }
 export async function fetchImage(source) {
     if (source.startsWith('data:')) {
-        const match = source.match(/^data:[^;]+;base64,(.+)$/);
-        if (!match)
+        const parsed = parseBase64DataUrl(source);
+        if (!parsed)
             throw new Error('Invalid data URL');
-        const b64 = match[1];
-        const approxBytes = Math.ceil((b64.length * 3) / 4);
+        const approxBytes = Math.ceil((parsed.base64.length * 3) / 4);
         if (approxBytes > getMaxDataUrlBytes())
             throw new Error('Data URL too large');
-        return Buffer.from(b64, 'base64');
+        return Buffer.from(parsed.base64, 'base64');
     }
     if (source.startsWith('http://') || source.startsWith('https://')) {
         return fetchHttpImage(source);
     }
     return fs.readFile(source);
 }
+/**
+ * Sniff image MIME type from magic bytes. Used to label the output of a
+ * failed `sharp` optimization (where we return original bytes but don't
+ * know the source MIME yet) and HTTP image responses whose Content-Type
+ * header is missing or wrong.
+ */
+export function sniffImageMime(buffer) {
+    if (buffer.length < 4)
+        return null;
+    // PNG: 89 50 4E 47 0D 0A 1A 0A
+    if (buffer[0] === 0x89 && buffer[1] === 0x50 && buffer[2] === 0x4e && buffer[3] === 0x47) {
+        return 'image/png';
+    }
+    // JPEG: FF D8 FF
+    if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    // GIF: 47 49 46 38
+    if (buffer[0] === 0x47 && buffer[1] === 0x49 && buffer[2] === 0x46 && buffer[3] === 0x38) {
+        return 'image/gif';
+    }
+    // WebP: RIFF....WEBP
+    if (buffer.length >= 12 &&
+        buffer[0] === 0x52 &&
+        buffer[1] === 0x49 &&
+        buffer[2] === 0x46 &&
+        buffer[3] === 0x46 &&
+        buffer[8] === 0x57 &&
+        buffer[9] === 0x45 &&
+        buffer[10] === 0x42 &&
+        buffer[11] === 0x50) {
+        return 'image/webp';
+    }
+    // BMP
+    if (buffer[0] === 0x42 && buffer[1] === 0x4d)
+        return 'image/bmp';
+    return null;
+}
+/**
+ * Optimize an image buffer and return both the base64 payload AND the MIME
+ * type that matches that payload. Callers should NOT assume JPEG — the
+ * pipeline falls back to the original bytes (with its detected MIME) when
+ * sharp is unavailable or fails. This closes BUG-012.
+ */
 export async function optimizeImage(buffer) {
     const sharp = await loadSharp();
-    if (!sharp)
-        return buffer.toString('base64');
+    if (!sharp) {
+        return {
+            base64: buffer.toString('base64'),
+            mime: sniffImageMime(buffer) ?? 'application/octet-stream',
+        };
+    }
     const maxDim = getMaxImageDimension();
     const quality = getImageJpegQuality();
     try {
@@ -94,17 +141,23 @@ export async function optimizeImage(buffer) {
             pipeline = pipeline.resize(opts);
         }
         const out = await pipeline.jpeg({ quality }).toBuffer();
-        return out.toString('base64');
+        return { base64: out.toString('base64'), mime: 'image/jpeg' };
     }
     catch {
-        return buffer.toString('base64');
+        return {
+            base64: buffer.toString('base64'),
+            mime: sniffImageMime(buffer) ?? 'application/octet-stream',
+        };
     }
 }
 export async function prepareImageUrl(source) {
     if (source.startsWith('data:'))
         return source;
     const buffer = await fetchImage(source);
-    const base64 = await optimizeImage(buffer);
-    const mime = source.startsWith('http') ? 'image/jpeg' : getMimeType(source);
-    return `data:${mime};base64,${base64}`;
+    const { base64, mime } = await optimizeImage(buffer);
+    // When optimization succeeded, mime is 'image/jpeg'. When it failed, we
+    // use the sniffed mime. For local files we prefer the extension-derived
+    // mime (more specific) when optimization fell back.
+    const finalMime = mime === 'image/jpeg' || source.startsWith('http') ? mime : getMimeType(source);
+    return `data:${finalMime};base64,${base64}`;
 }

package/dist/tool-handlers/openrouter-errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+import { type ToolErrorResult } from '../errors.js';
+/**
+ * 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.
+ */
+export declare function classifyUpstreamError(err: unknown, _contextMessage?: string): ToolErrorResult;

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

@@ -0,0 +1,99 @@
+/**
+ * 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.
+ */
+import { ErrorCode, toolError } from '../errors.js';
+function extractStatus(err) {
+    if (typeof err !== 'object' || err === null)
+        return undefined;
+    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)
+            return parseInt(m[1], 10);
+    }
+    return undefined;
+}
+function extractMessage(err) {
+    if (err instanceof Error) {
+        const nested = err.error;
+        if (nested && typeof nested === 'object' && typeof nested.message === 'string') {
+            return `${err.message} — ${nested.message}`;
+        }
+        if (typeof nested === 'string')
+            return `${err.message} — ${nested}`;
+        return err.message;
+    }
+    if (typeof err === 'string')
+        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.
+ */
+export function classifyUpstreamError(err, _contextMessage) {
+    const msg = extractMessage(err);
+    const status = extractStatus(err);
+    const lower = msg.toLowerCase();
+    const fullMsg = msg;
+    // Explicit credit / balance signals.
+    if (lower.includes('insufficient balance') ||
+        lower.includes('insufficient credits') ||
+        lower.includes('requires more credits') ||
+        lower.includes('requires at least') ||
+        status === 402) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'credits' });
+    }
+    // Zero Data Retention.
+    if (lower.includes('zdr') || lower.includes('zero data retention')) {
+        return toolError(ErrorCode.ZDR_INCOMPATIBLE, fullMsg, { status });
+    }
+    // Model lookup failures.
+    if (lower.includes('model') &&
+        (lower.includes('does not exist') || lower.includes('not found') || lower.includes('invalid model'))) {
+        return toolError(ErrorCode.MODEL_NOT_FOUND, fullMsg, { status });
+    }
+    // Content policy / moderation — surface as UPSTREAM_REFUSED so callers can distinguish from 5xx.
+    if (lower.includes('content policy') || lower.includes('moderation') || lower.includes('refused')) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'policy' });
+    }
+    // Rate-limit specific.
+    if (status === 429 || lower.includes('rate limit')) {
+        return toolError(ErrorCode.UPSTREAM_REFUSED, fullMsg, { status, reason: 'rate_limit' });
+    }
+    // Timeouts (AbortError from `AbortSignal.timeout`).
+    if (lower.includes('timed out') ||
+        lower.includes('timeout') ||
+        lower.includes('aborted') ||
+        (err instanceof Error && err.name === 'AbortError')) {
+        return toolError(ErrorCode.UPSTREAM_TIMEOUT, fullMsg, { status });
+    }
+    // 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 });
+    }
+    return toolError(ErrorCode.UPSTREAM_HTTP, fullMsg);
+}

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

@@ -0,0 +1,11 @@
+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.
+ */
+export declare function resolveSafeOutputPath(savePath: string): Promise<string>;

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

@@ -0,0 +1,88 @@
+/**
+ * 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';
+function getOutputRoot() {
+    const override = process.env.OPENROUTER_OUTPUT_DIR;
+    if (override && override.length > 0)
+        return path.resolve(override);
+    return process.cwd();
+}
+function isUnsafeMode() {
+    const v = process.env.OPENROUTER_ALLOW_UNSAFE_PATHS;
+    return v === '1' || v?.toLowerCase() === 'true';
+}
+export class UnsafeOutputPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UnsafeOutputPathError';
+    }
+}
+/**
+ * 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.
+ */
+export async function resolveSafeOutputPath(savePath) {
+    if (isUnsafeMode()) {
+        const abs = path.resolve(savePath);
+        await fs.mkdir(path.dirname(abs), { recursive: true });
+        return abs;
+    }
+    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}).`);
+    }
+    return path.join(parentReal, path.basename(candidate));
+}
+async function findExistingAncestor(dir) {
+    let current = dir;
+    for (;;) {
+        try {
+            await fs.access(current);
+            return current;
+        }
+        catch {
+            const parent = path.dirname(current);
+            if (parent === current)
+                return current; // reached root
+            current = parent;
+        }
+    }
+}

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

@@ -1,8 +1,6 @@
 export async function handleSearchModels(request, apiClient, modelCache) {
     try {
-        if (!modelCache.isValid()) {
-            modelCache.setModels(await apiClient.getModels());
-        }
+        await modelCache.ensureFresh(() => apiClient.getModels());
         const results = modelCache.search(request.params.arguments);
         return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
     }

package/dist/tool-handlers/validate-model.js

@@ -1,6 +1,12 @@
 export async function handleValidateModel(request, modelCache, apiClient) {
-    if (!modelCache.isValid() && apiClient) {
-        modelCache.setModels(await apiClient.getModels());
+    if (apiClient) {
+        try {
+            await modelCache.ensureFresh(() => apiClient.getModels());
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+        }
     }
     if (!modelCache.isValid()) {
         return { content: [{ type: 'text', text: 'No model data available.' }], isError: true };

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

@@ -0,0 +1,29 @@
+export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
+export declare const SUPPORTED_VIDEO_FORMATS: readonly ["mp4", "mpeg", "mov", "webm"];
+export type VideoFormat = (typeof SUPPORTED_VIDEO_FORMATS)[number];
+/** Map a file extension (without the dot) to a canonical VideoFormat. */
+export declare function getVideoFormat(filePath: string): VideoFormat | undefined;
+/** Canonical MIME type for each format. */
+export declare function getVideoMimeType(format: VideoFormat): string;
+/**
+ * Detect a container from the first bytes of a buffer. Recognizes mp4/mov
+ * (`ftyp` box at offset 4), webm (EBML magic `1A 45 DF A3`), and MPEG-PS
+ * (`00 00 01 BA` / `00 00 01 B3`). Returns `undefined` if no match.
+ *
+ * Intentionally conservative: if the magic doesn't match, the caller falls
+ * back to the filename / Content-Type.
+ */
+export declare function detectVideoFormat(buffer: Buffer): VideoFormat | undefined;
+export interface VideoData {
+    data: string;
+    format: VideoFormat;
+    mediaType: string;
+    sizeBytes: number;
+}
+/**
+ * Prepare a video from any source (data URL / HTTP URL / local file) as
+ * base64 + MIME. OpenRouter requires the client to send video as either a
+ * URL or a data URL; we always base64 it so the tool works regardless of
+ * provider quirks.
+ */
+export declare function prepareVideoData(source: string): Promise<VideoData>;

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

@@ -0,0 +1,174 @@
+/**
+ * Video format detection and fetch utilities. Mirrors the structure of
+ * `audio-utils.ts`: all network/security logic comes from `fetch-utils.ts`,
+ * this module owns format detection, base64 encoding, and MIME mapping.
+ *
+ * OpenRouter's video-understanding docs (accessed 2026-04-20) list four
+ * supported container formats: mp4, mpeg, mov, webm.
+ */
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { readEnvInt, fetchHttpResource, parseBase64DataUrl } from './fetch-utils.js';
+export { isBlockedIPv4, assertUrlSafeForFetch } from './fetch-utils.js';
+const DEFAULT_FETCH_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_DOWNLOAD_BYTES = 100 * 1024 * 1024; // 100 MB
+const DEFAULT_MAX_REDIRECTS = 8;
+const DEFAULT_MAX_DATA_URL_BYTES = 100 * 1024 * 1024;
+function getFetchTimeoutMs() {
+    return readEnvInt('OPENROUTER_VIDEO_FETCH_TIMEOUT_MS', DEFAULT_FETCH_TIMEOUT_MS, 1000);
+}
+function getMaxDownloadBytes() {
+    return readEnvInt('OPENROUTER_VIDEO_MAX_DOWNLOAD_BYTES', DEFAULT_MAX_DOWNLOAD_BYTES, 1024);
+}
+function getMaxRedirects() {
+    return readEnvInt('OPENROUTER_VIDEO_MAX_REDIRECTS', DEFAULT_MAX_REDIRECTS, 0);
+}
+function getMaxDataUrlBytes() {
+    return readEnvInt('OPENROUTER_VIDEO_MAX_DATA_URL_BYTES', DEFAULT_MAX_DATA_URL_BYTES, 1024);
+}
+export const SUPPORTED_VIDEO_FORMATS = ['mp4', 'mpeg', 'mov', 'webm'];
+/** Map a file extension (without the dot) to a canonical VideoFormat. */
+export function getVideoFormat(filePath) {
+    const ext = path.extname(filePath).toLowerCase().slice(1);
+    const alias = {
+        mp4: 'mp4',
+        m4v: 'mp4',
+        mpeg: 'mpeg',
+        mpg: 'mpeg',
+        mov: 'mov',
+        qt: 'mov',
+        webm: 'webm',
+    };
+    return alias[ext];
+}
+/** Canonical MIME type for each format. */
+export function getVideoMimeType(format) {
+    const map = {
+        mp4: 'video/mp4',
+        mpeg: 'video/mpeg',
+        mov: 'video/mov',
+        webm: 'video/webm',
+    };
+    return map[format];
+}
+function mimeSubtypeToFormat(subtype) {
+    const aliasMap = {
+        mp4: 'mp4',
+        'x-m4v': 'mp4',
+        mpeg: 'mpeg',
+        mov: 'mov',
+        quicktime: 'mov',
+        'x-quicktime': 'mov',
+        webm: 'webm',
+    };
+    const lower = subtype.toLowerCase();
+    return aliasMap[lower];
+}
+function formatFromContentType(ct) {
+    if (!ct)
+        return undefined;
+    const mime = ct.split(';')[0].trim().toLowerCase();
+    if (!mime.startsWith('video/'))
+        return undefined;
+    return mimeSubtypeToFormat(mime.slice(6));
+}
+/**
+ * Detect a container from the first bytes of a buffer. Recognizes mp4/mov
+ * (`ftyp` box at offset 4), webm (EBML magic `1A 45 DF A3`), and MPEG-PS
+ * (`00 00 01 BA` / `00 00 01 B3`). Returns `undefined` if no match.
+ *
+ * Intentionally conservative: if the magic doesn't match, the caller falls
+ * back to the filename / Content-Type.
+ */
+export function detectVideoFormat(buffer) {
+    if (buffer.length >= 12) {
+        const box = buffer.subarray(4, 8).toString('ascii');
+        if (box === 'ftyp') {
+            // Brand tells mp4 vs mov. 'qt  ' and 'mov ' indicate QuickTime.
+            const brand = buffer.subarray(8, 12).toString('ascii');
+            if (brand === 'qt  ' || brand === 'mov ')
+                return 'mov';
+            return 'mp4';
+        }
+    }
+    if (buffer.length >= 4) {
+        // EBML header — WebM & Matroska.
+        if (buffer[0] === 0x1a &&
+            buffer[1] === 0x45 &&
+            buffer[2] === 0xdf &&
+            buffer[3] === 0xa3) {
+            return 'webm';
+        }
+        // MPEG-PS / MPEG-TS start codes.
+        if (buffer[0] === 0x00 &&
+            buffer[1] === 0x00 &&
+            buffer[2] === 0x01 &&
+            (buffer[3] === 0xba || buffer[3] === 0xb3 || buffer[3] === 0xe0)) {
+            return 'mpeg';
+        }
+    }
+    return undefined;
+}
+/**
+ * Prepare a video from any source (data URL / HTTP URL / local file) as
+ * base64 + MIME. OpenRouter requires the client to send video as either a
+ * URL or a data URL; we always base64 it so the tool works regardless of
+ * provider quirks.
+ */
+export async function prepareVideoData(source) {
+    // --- data URL ---
+    if (source.startsWith('data:')) {
+        const parsed = parseBase64DataUrl(source);
+        if (!parsed)
+            throw new Error('Invalid video data URL');
+        if (!parsed.mediaType.startsWith('video/')) {
+            throw new Error(`Data URL is not a video/* MIME: ${parsed.mediaType}`);
+        }
+        const format = mimeSubtypeToFormat(parsed.mediaType.slice(6));
+        if (!format) {
+            throw new Error(`Unsupported video format from MIME: ${parsed.mediaType}. Supported: ${SUPPORTED_VIDEO_FORMATS.join(', ')}`);
+        }
+        const approxBytes = Math.ceil((parsed.base64.length * 3) / 4);
+        if (approxBytes > getMaxDataUrlBytes())
+            throw new Error('Video data URL too large');
+        return {
+            data: parsed.base64,
+            format,
+            mediaType: getVideoMimeType(format),
+            sizeBytes: approxBytes,
+        };
+    }
+    // --- HTTP(S) URL ---
+    if (source.startsWith('http://') || source.startsWith('https://')) {
+        const { buffer, contentType } = await fetchHttpResource(source, {
+            timeoutMs: getFetchTimeoutMs(),
+            maxBytes: getMaxDownloadBytes(),
+            maxRedirects: getMaxRedirects(),
+        });
+        const urlPath = new URL(source).pathname;
+        const format = detectVideoFormat(buffer) ??
+            getVideoFormat(urlPath) ??
+            formatFromContentType(contentType);
+        if (!format) {
+            throw new Error(`Could not determine video format from ${source}. Supported: ${SUPPORTED_VIDEO_FORMATS.join(', ')}`);
+        }
+        return {
+            data: buffer.toString('base64'),
+            format,
+            mediaType: getVideoMimeType(format),
+            sizeBytes: buffer.length,
+        };
+    }
+    // --- local file ---
+    const buffer = await fs.readFile(source);
+    const format = detectVideoFormat(buffer) ?? getVideoFormat(source);
+    if (!format) {
+        throw new Error(`Unsupported video format for file: ${source}. Supported: ${SUPPORTED_VIDEO_FORMATS.join(', ')}`);
+    }
+    return {
+        data: buffer.toString('base64'),
+        format,
+        mediaType: getVideoMimeType(format),
+        sizeBytes: buffer.length,
+    };
+}