@juspay/neurolink 10.10.11 → 10.11.0

package/dist/lib/utils/imageProcessor.js

@@ -3,6 +3,7 @@
  * Handles format conversion for different AI providers
  */
 import { basename } from "path";
+import { SUPPORTED_INPUT_IMAGE_MIME_TYPES } from "../adapters/imageFormatSupport.js";
 import { logger } from "./logger.js";
 import { redactPathFromMessage, redactUrlForError, redactUrlsInText, sanitizeErrorCause, } from "./logSanitize.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
@@ -565,23 +566,19 @@ export class ImageProcessor {
      * Validate image format
      */
     static validateImageFormat(mediaType) {
-        const supportedFormats = [
-            "image/jpeg",
-            "image/png",
-            "image/gif",
-            "image/webp",
-            "image/bmp",
-            "image/tiff",
-            "image/svg+xml",
-            "image/avif",
-            // Deliberately excludes "application/octet-stream": that's
-            // detectImageType()'s honest sentinel for bytes matching no known
-            // image signature (#261), not a real image format. Vision providers
-            // (OpenAI/Anthropic/Google) reject it outright with an HTTP 400, so
-            // process() must fail loud instead of packaging it as a valid image
-            // (see the octet-stream guard in process() below).
-        ];
-        return supportedFormats.includes(mediaType.toLowerCase());
+        // Derived from the canonical input set rather than hand-listed. The old
+        // literal omitted HEIC, HEIF, ICO and JPEG 2000, so an iPhone photo
+        // attached by path was rejected here — "Invalid MIME type: image/heic is
+        // not in allowed list" — before the transcode that exists to accept it
+        // could run. Intake has to allow every format we can convert, not just the
+        // ones providers take unchanged.
+        //
+        // Still excludes "application/octet-stream": that is detectImageType()'s
+        // honest sentinel for bytes matching no known image signature (#261), not
+        // a real format. Vision providers reject it with an HTTP 400, so process()
+        // must fail loud rather than package it as a valid image (see the
+        // octet-stream guard in process() below).
+        return SUPPORTED_INPUT_IMAGE_MIME_TYPES.has(mediaType.toLowerCase());
     }
     /**
      * Get image dimensions from Buffer (basic implementation)

package/dist/lib/utils/markupSniff.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Content sniffing for text-shaped image formats.
+ *
+ * SVG is markup, so it has no byte signature — but it does have an unambiguous
+ * root element, and identifying it matters twice over: the detector routes SVG
+ * to the sanitizer rather than to a vision API, and the image path must not let
+ * SVG bytes travel under some other format's MIME type.
+ *
+ * ## Why this is a scan and not a regular expression
+ *
+ * The obvious implementation strips the prolog with a pattern like
+ * `(?:<!--[\s\S]*?-->\s*)*<svg`. That is two nested quantifiers, and CodeQL
+ * rightly flags it as `js/redos`: input beginning `<!--` and repeating
+ * `--><!--` drives exponential backtracking, so a hostile (or merely odd)
+ * upload can burn CPU inside what is supposed to be a cheap type check.
+ *
+ * The `.replace()`-chain alternative is unsound for a different reason —
+ * removing a multi-character construct can join the surrounding text into a
+ * fresh instance of that same construct, so one pass does not converge
+ * (`<!--<!-- -->-->` leaves a comment behind). CodeQL flags that shape too, as
+ * `js/incomplete-multi-character-sanitization`.
+ *
+ * A single forward scan has neither problem: the cursor only ever advances, so
+ * the work is linear in the input and no construct can re-form behind it.
+ *
+ * @module utils/markupSniff
+ */
+/**
+ * Whether the leading bytes are an SVG document.
+ *
+ * Requires `<svg` to be the *root element* rather than merely present, so an
+ * HTML page embedding an inline `<svg>` icon is not mistaken for a standalone
+ * image. A BOM, XML declaration, DOCTYPE and comments may precede it.
+ *
+ * @param input - Buffer or string to inspect; only the head is read.
+ */
+export declare function looksLikeSvgMarkup(input: Buffer | string): boolean;

package/dist/lib/utils/markupSniff.js

@@ -0,0 +1,125 @@
+/**
+ * Content sniffing for text-shaped image formats.
+ *
+ * SVG is markup, so it has no byte signature — but it does have an unambiguous
+ * root element, and identifying it matters twice over: the detector routes SVG
+ * to the sanitizer rather than to a vision API, and the image path must not let
+ * SVG bytes travel under some other format's MIME type.
+ *
+ * ## Why this is a scan and not a regular expression
+ *
+ * The obvious implementation strips the prolog with a pattern like
+ * `(?:<!--[\s\S]*?-->\s*)*<svg`. That is two nested quantifiers, and CodeQL
+ * rightly flags it as `js/redos`: input beginning `<!--` and repeating
+ * `--><!--` drives exponential backtracking, so a hostile (or merely odd)
+ * upload can burn CPU inside what is supposed to be a cheap type check.
+ *
+ * The `.replace()`-chain alternative is unsound for a different reason —
+ * removing a multi-character construct can join the surrounding text into a
+ * fresh instance of that same construct, so one pass does not converge
+ * (`<!--<!-- -->-->` leaves a comment behind). CodeQL flags that shape too, as
+ * `js/incomplete-multi-character-sanitization`.
+ *
+ * A single forward scan has neither problem: the cursor only ever advances, so
+ * the work is linear in the input and no construct can re-form behind it.
+ *
+ * @module utils/markupSniff
+ */
+/** Bytes inspected when sniffing for a markup root element. */
+const MARKUP_SNIFF_LIMIT = 1024;
+/**
+ * Whether the leading bytes are an SVG document.
+ *
+ * Requires `<svg` to be the *root element* rather than merely present, so an
+ * HTML page embedding an inline `<svg>` icon is not mistaken for a standalone
+ * image. A BOM, XML declaration, DOCTYPE and comments may precede it.
+ *
+ * @param input - Buffer or string to inspect; only the head is read.
+ */
+export function looksLikeSvgMarkup(input) {
+    const head = typeof input === "string"
+        ? input.slice(0, MARKUP_SNIFF_LIMIT)
+        : input.toString("utf8", 0, Math.min(input.length, MARKUP_SNIFF_LIMIT));
+    if (!head.includes("<svg")) {
+        return false;
+    }
+    let cursor = head.charCodeAt(0) === 0xfeff ? 1 : 0;
+    while (cursor < head.length) {
+        while (cursor < head.length && /\s/.test(head[cursor])) {
+            cursor++;
+        }
+        if (head[cursor] !== "<") {
+            // Text before any element — not a well-formed XML document.
+            return false;
+        }
+        // Each prolog construct ends at a known delimiter; an unterminated one
+        // means the document is truncated or malformed, so stop rather than guess.
+        let end;
+        if (head.startsWith("<?", cursor)) {
+            end = head.indexOf("?>", cursor + 2);
+            cursor = end === -1 ? head.length : end + 2;
+        }
+        else if (head.startsWith("<!--", cursor)) {
+            end = head.indexOf("-->", cursor + 4);
+            cursor = end === -1 ? head.length : end + 3;
+        }
+        else if (head.startsWith("<!", cursor)) {
+            // DOCTYPE. Stopping at the first '>' is wrong for two legal forms: a
+            // quoted public/system identifier may contain '>', and an internal
+            // subset (`<!DOCTYPE svg [ <!ENTITY x "y"> ]>`) certainly does. Either
+            // one left the cursor mid-declaration and made a valid SVG classify as
+            // not-SVG. Track quotes and subset depth to find the real terminator.
+            cursor = skipDoctype(head, cursor);
+        }
+        else {
+            // First real element decides.
+            return /^<svg[\s>/]/i.test(head.slice(cursor));
+        }
+    }
+    return false;
+}
+/**
+ * Return the index just past a DOCTYPE declaration beginning at `start`.
+ *
+ * Handles quoted identifiers and a bracketed internal subset. Returns
+ * `head.length` when the declaration is unterminated within the sniffed
+ * window, which stops the caller rather than letting it guess.
+ */
+function skipDoctype(head, start) {
+    let quote = null;
+    let subsetDepth = 0;
+    for (let i = start + 2; i < head.length; i++) {
+        const ch = head[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        // A comment inside the internal subset may itself contain ']' and '>'.
+        // Treating those as structural closed the subset early and terminated the
+        // DOCTYPE on the comment's own '-->', so valid SVG classified as not-SVG.
+        if (head.startsWith("<!--", i)) {
+            const commentEnd = head.indexOf("-->", i + 4);
+            if (commentEnd === -1) {
+                return head.length;
+            }
+            i = commentEnd + 2; // loop increment steps past the final '>'
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+        }
+        else if (ch === "[") {
+            subsetDepth++;
+        }
+        else if (ch === "]") {
+            subsetDepth = Math.max(0, subsetDepth - 1);
+        }
+        else if (ch === ">" && subsetDepth === 0) {
+            return i + 1;
+        }
+    }
+    return head.length;
+}
+//# sourceMappingURL=markupSniff.js.map

package/dist/lib/utils/messageBuilder.d.ts

@@ -52,3 +52,17 @@ export declare function processUnifiedFilesArray(options: GenerateOptions, maxSi
  * Detects when images are present and routes through provider adapter
  */
 export declare function buildMultimodalMessagesArray(options: GenerateOptions, provider: string, model: string): Promise<MultimodalChatMessage[]>;
+/**
+ * Transcode any image in `input.images` that no vision provider accepts,
+ * rewriting the entry in place as a PNG data URI.
+ *
+ * Mutates in place and is idempotent, matching `processUnifiedFilesArray` and
+ * `foldMediaAliasesIntoFiles`: the shared multimodal builder and the providers
+ * that bypass it (Google AI Studio's and Vertex's native SDK paths, Bedrock's
+ * Converse path) can all call it on the same options object without converting
+ * anything twice.
+ *
+ * Entries that are `http(s)` URLs are left alone — they have no bytes yet, and
+ * `processImageToBase64` converts them once they are downloaded.
+ */
+export declare function normalizeVisionImageFormats(input: GenerateOptions["input"]): Promise<void>;

package/dist/lib/utils/messageBuilder.js

@@ -8,11 +8,16 @@ import { PDF_LIMITS } from "../core/constants.js";
 import { enforceAggregateFileBudget, FILE_READ_BUDGET_PERCENT, } from "../context/fileTokenBudget.js";
 import { isCSVContent, SIZE_TIER_THRESHOLDS } from "../types/index.js";
 import { tracers, ATTR, withSpan } from "../telemetry/index.js";
+import { needsVisionTranscode, toVisionCompatibleImage, } from "../adapters/imageFormatSupport.js";
+import { FILE_TYPE_REGISTRY, lookupByExtension, } from "../processors/config/fileTypeRegistry.js";
 import { ErrorFactory, NeuroLinkError, withTimeout } from "./errorHandling.js";
 import { FileDetector } from "./fileDetector.js";
+import { detectIsoBmffImageMimeType } from "./isoBmff.js";
 import { getImageCache } from "./imageCache.js";
 import { ImageProcessor, imageUtils } from "./imageProcessor.js";
 import { logger } from "./logger.js";
+import { looksLikeSvgMarkup } from "./markupSniff.js";
+import { redactUrlForError } from "./logSanitize.js";
 import { PDFImageConverter, PDFProcessor } from "./pdfProcessor.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
 import { estimateTokens } from "./tokenEstimation.js";
@@ -22,63 +27,16 @@ import { estimateTokens } from "./tokenEstimation.js";
 // classify files into broad categories (video, audio, image, etc.) so
 // estimatePostProcessingTokens() can use type-aware estimates.
 // ---------------------------------------------------------------------------
-/** Extension → file type mapping for budget estimation */
-const EXTENSION_TYPE_MAP = {
-    // Video
-    mp4: "video",
-    mkv: "video",
-    mov: "video",
-    avi: "video",
-    webm: "video",
-    wmv: "video",
-    flv: "video",
-    m4v: "video",
-    // Audio
-    mp3: "audio",
-    wav: "audio",
-    ogg: "audio",
-    flac: "audio",
-    m4a: "audio",
-    aac: "audio",
-    wma: "audio",
-    opus: "audio",
-    // Image
-    jpg: "image",
-    jpeg: "image",
-    png: "image",
-    gif: "image",
-    webp: "image",
-    bmp: "image",
-    tiff: "image",
-    tif: "image",
-    avif: "image",
-    // Archive
-    zip: "archive",
-    tar: "archive",
-    gz: "archive",
-    tgz: "archive",
-    rar: "archive",
-    "7z": "archive",
-    jar: "archive",
-    // Documents
-    xlsx: "xlsx",
-    xls: "xlsx",
-    ods: "xlsx",
-    docx: "docx",
-    doc: "docx",
-    odt: "docx",
-    rtf: "docx",
-    pptx: "pptx",
-    ppt: "pptx",
-    odp: "pptx",
-    // PDF
-    pdf: "pdf",
-    // SVG
-    svg: "svg",
-    // CSV
-    csv: "csv",
-    tsv: "csv",
-};
+/**
+ * Extension → file type for budget estimation.
+ *
+ * Derived from the canonical registry rather than hand-listed: this was a
+ * fourth copy of the same knowledge, and it disagreed with the detector it is
+ * supposed to predict — it had no entry for .mpg/.mpeg/.3gp/.aiff and so on, so
+ * estimatePostProcessingTokens() silently fell back to a generic estimate for
+ * exactly the large media files whose estimate matters most.
+ */
+const EXTENSION_TYPE_MAP = Object.fromEntries(FILE_TYPE_REGISTRY.flatMap((entry) => entry.extensions.map((ext) => [ext.slice(1), entry.fileType])));
 /**
  * Infer file type from extension in a file path or URL.
  * Returns undefined if no extension or unrecognized.
@@ -101,6 +59,19 @@ function inferFileTypeFromBuffer(buf) {
     if (buf.length < 4) {
         return undefined;
     }
+    // SVG is markup and has no magic number, so every signature check below
+    // misses it and a raw SVG Buffer classified as `undefined` — which meant the
+    // lazy path, which previews markup away. Checked first because the sniff is
+    // a cheap look at the head and cannot collide with a binary signature.
+    //
+    // Deliberately a substring scan over the head rather than a prolog-stripping
+    // regex: the obvious pattern for skipping comments and a DOCTYPE is two
+    // nested quantifiers, which is a ReDoS waiting to happen inside what is
+    // supposed to be a cheap type check. Over-matching is harmless here — the
+    // only consequence of a false positive is that a file is processed eagerly.
+    if (buf.subarray(0, 1024).toString("latin1").includes("<svg")) {
+        return "svg";
+    }
     // PNG
     if (buf[0] === 0x89 &&
         buf[1] === 0x50 &&
@@ -863,7 +834,9 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
             try {
                 // ─── Lazy file registration path ──────────────────────────────
                 const fileSize = fileRegistry ? getFileSize(file) : 0;
-                if (fileRegistry && fileSize > SIZE_TIER_THRESHOLDS.TINY_MAX) {
+                if (fileRegistry &&
+                    fileSize > SIZE_TIER_THRESHOLDS.TINY_MAX &&
+                    !isEagerMultimodalFile(file)) {
                     const registered = await tryRegisterFileReference(file, fileSize, fileRegistry, fileIdx);
                     if (registered) {
                         logger.info(`[NEUROLINK] File lazily registered: ${filename} (${fileSize} bytes) — deferred processing`);
@@ -1231,6 +1204,9 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     enforceFileBudget(options, provider, model);
     // Process unified files array (auto-detect)
     await processUnifiedFilesArray(options, maxSize, provider);
+    // Detection can append images (PDF page renders, video keyframes, a HEIC
+    // photo), so compatibility conversion has to run after it, not before.
+    await normalizeVisionImageFormats(inp);
     // Process explicit CSV files array
     await processExplicitCsvFiles(options);
     // Post-processing budget enforcement and token usage logging
@@ -1542,25 +1518,24 @@ async function downloadImageFromUrl(url) {
     }
 }
 /**
- * Get MIME type from file extension
+ * Get MIME type from an image file extension.
+ *
+ * Delegates to the canonical registry instead of the six-case switch this used
+ * to be. That switch covered png/gif/webp/bmp/tiff and defaulted *everything
+ * else* to image/jpeg, so a .heic, .avif, .ico or .jp2 path was labelled JPEG
+ * — which meant `needsVisionTranscode()` never fired for it and the raw bytes
+ * went to the provider under a MIME type that was simply untrue. Exactly the
+ * kind of hand-maintained table this registry exists to delete.
+ *
+ * The image/jpeg fallback is kept only for genuinely unknown extensions, since
+ * callers here have already established they are handling an image.
  */
 function getMimeTypeFromExtension(filePath) {
-    const ext = filePath.toLowerCase().split(".").pop();
-    switch (ext) {
-        case "png":
-            return "image/png";
-        case "gif":
-            return "image/gif";
-        case "webp":
-            return "image/webp";
-        case "bmp":
-            return "image/bmp";
-        case "tiff":
-        case "tif":
-            return "image/tiff";
-        default:
-            return "image/jpeg";
+    const entry = lookupByExtension(filePath);
+    if (entry?.modality === "image") {
+        return entry.mimeTypes[0];
     }
+    return "image/jpeg";
 }
 /**
  * Detect MIME type from buffer magic bytes
@@ -1624,6 +1599,45 @@ function detectMimeTypeFromBuffer(buffer) {
                 buffer[3] === 0x2a))) {
         return "image/tiff";
     }
+    // The formats above are the ones a provider accepts (or that sharp handles
+    // trivially). Everything below is a format NO vision provider accepts, and
+    // recognising it here is what lets `needsVisionTranscode()` fire — a Buffer
+    // whose format was unrecognised fell through to the image/jpeg default and
+    // was shipped to the provider unconverted under a MIME type that was false.
+    // Raw Buffers are the most direct way a backend attaches an image, so this
+    // was the single biggest hole in the vision-compatibility path.
+    // HEIC / HEIF / AVIF: ISO-BMFF `ftyp` box, distinguished by major brand.
+    // Shared with the FileDetector so the two cannot drift on brand tables.
+    const isoBmffImage = detectIsoBmffImageMimeType(buffer);
+    if (isoBmffImage) {
+        return isoBmffImage;
+    }
+    // ICO: 00 00 01 00. Checked after the ftyp probe because an ISO-BMFF file
+    // also starts with a zero byte.
+    if (buffer.length >= 4 &&
+        buffer[0] === 0x00 &&
+        buffer[1] === 0x00 &&
+        buffer[2] === 0x01 &&
+        buffer[3] === 0x00) {
+        return "image/x-icon";
+    }
+    // SVG is markup, so it has no byte signature — and without this probe a raw
+    // SVG buffer matched nothing, kept processImageToBase64's "image/jpeg"
+    // default, and was shipped to the provider as XML labelled as a JPEG.
+    // Shared forward scan rather than a local regex: the regex form of this
+    // check is a CodeQL js/redos finding (see markupSniff).
+    if (looksLikeSvgMarkup(buffer)) {
+        return "image/svg+xml";
+    }
+    // JPEG 2000: 12-byte signature box "....jP  ".
+    if (buffer.length >= 8 &&
+        buffer[0] === 0x00 &&
+        buffer[1] === 0x00 &&
+        buffer[2] === 0x00 &&
+        buffer[3] === 0x0c &&
+        buffer.toString("latin1", 4, 8) === "jP  ") {
+        return "image/jp2";
+    }
     return undefined;
 }
 /**
@@ -1730,8 +1744,108 @@ async function processImageToBase64(image, index) {
         ImageProcessor.validateBufferSize(image, `image input at index ${index}`);
         imageData = image.toString("base64");
     }
+    // Last line of defence for vision-format compatibility. `normalizeVisionImageFormats`
+    // handles `input.images` eagerly so the providers that read that array
+    // directly (Google AI Studio, Bedrock) see converted bytes, but images that
+    // arrive as URLs are downloaded further downstream and only become bytes
+    // here. A no-op for the universal formats, so the common path is unaffected.
+    if (needsVisionTranscode(mimeType)) {
+        const compatible = await toVisionCompatibleImage(Buffer.from(imageData, "base64"), mimeType);
+        if (compatible.converted) {
+            imageData = compatible.buffer.toString("base64");
+            mimeType = compatible.mimeType;
+        }
+    }
     return { imageData, mimeType };
 }
+/**
+ * Transcode any image in `input.images` that no vision provider accepts,
+ * rewriting the entry in place as a PNG data URI.
+ *
+ * Mutates in place and is idempotent, matching `processUnifiedFilesArray` and
+ * `foldMediaAliasesIntoFiles`: the shared multimodal builder and the providers
+ * that bypass it (Google AI Studio's and Vertex's native SDK paths, Bedrock's
+ * Converse path) can all call it on the same options object without converting
+ * anything twice.
+ *
+ * Entries that are `http(s)` URLs are left alone — they have no bytes yet, and
+ * `processImageToBase64` converts them once they are downloaded.
+ */
+export async function normalizeVisionImageFormats(input) {
+    const images = input?.images;
+    if (!images || images.length === 0) {
+        return;
+    }
+    for (let index = 0; index < images.length; index++) {
+        const entry = images[index];
+        // ImageWithAltText wraps the payload in `.data`; convert that and keep the
+        // alt text attached rather than dropping the wrapper.
+        const isWrapped = typeof entry === "object" && entry !== null && !Buffer.isBuffer(entry);
+        const payload = isWrapped
+            ? entry.data
+            : entry;
+        const source = await readImageSourceForConversion(payload);
+        if (!source || !needsVisionTranscode(source.mimeType)) {
+            continue;
+        }
+        const compatible = await toVisionCompatibleImage(source.buffer, source.mimeType);
+        if (!compatible.converted) {
+            continue;
+        }
+        const dataUri = `data:${compatible.mimeType};base64,${compatible.buffer.toString("base64")}`;
+        images[index] = isWrapped
+            ? { ...entry, data: dataUri }
+            : dataUri;
+    }
+}
+/**
+ * Resolve one `input.images` entry to bytes plus a MIME type, or undefined when
+ * it cannot be resolved without a network call.
+ *
+ * File paths are only read when their extension says the format would need
+ * conversion. Reading every attached .png off disk just to confirm it is
+ * already compatible would double the I/O of the common case for no benefit.
+ */
+async function readImageSourceForConversion(payload) {
+    if (Buffer.isBuffer(payload)) {
+        const mimeType = detectMimeTypeFromBuffer(payload);
+        return mimeType ? { buffer: payload, mimeType } : undefined;
+    }
+    if (typeof payload !== "string") {
+        return undefined;
+    }
+    if (payload.startsWith("data:")) {
+        const match = payload.match(/^data:([^;]+);base64,(.+)$/);
+        return match
+            ? { buffer: Buffer.from(match[2], "base64"), mimeType: match[1] }
+            : undefined;
+    }
+    if (isInternetUrl(payload)) {
+        return undefined;
+    }
+    const mimeType = getMimeTypeFromExtension(payload);
+    if (!needsVisionTranscode(mimeType)) {
+        return undefined;
+    }
+    try {
+        // Preflight the size before reading. Conversion replaces the entry with a
+        // data URI, which bypasses processImageToBase64's buffer-size guard — so
+        // without this a large local HEIC/TIFF/BMP was read fully into memory and
+        // then re-encoded, with no limit applied at either step.
+        const { size } = await statAsync(payload);
+        ImageProcessor.validateSize(size, `image at ${safeBasename(payload)}`);
+        const buffer = await readFileAsync(payload);
+        ImageProcessor.validateBufferSize(buffer, `image at ${safeBasename(payload)}`);
+        return { buffer, mimeType };
+    }
+    catch (error) {
+        // The path may be a signed URL or carry credentials in query params, so it
+        // is redacted rather than interpolated verbatim (see logSanitize).
+        logger.warn(`[messageBuilder] Could not read ${redactUrlForError(payload)} for image ` +
+            `format conversion: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
 /**
  * Convert simple images format to Vercel AI SDK format with smart auto-detection
  * - URLs: Downloaded and converted to base64 for Vercel AI SDK compatibility
@@ -2027,6 +2141,105 @@ function getFileSource(file) {
     }
     return "buffer";
 }
+/**
+ * Whether a file must be processed eagerly rather than lazily referenced.
+ *
+ * The lazy path registers a file and injects a short textual *preview* in place
+ * of the file itself. Whether that is an acceptable trade depends entirely on
+ * whether a description of the file can answer questions about it:
+ *
+ *   pdf    lazy -> preview carries the extracted text   ✔ content survives
+ *   image  lazy -> preview carries ~98 chars of prose   ✘ the pixels are gone
+ *
+ * An image is the case where the bytes ARE the content: no prose summary
+ * substitutes for them, so the model receives a description of a file instead
+ * of the file. Measured end-to-end on `release`, asking "what number is
+ * written in this image?":
+ *
+ *   tiny.png  1.6 KB -> "7391"              (under TINY_MAX, eager, correct)
+ *   big.png    11 KB -> NOTHING_RECEIVED    (lazy, image never arrived)
+ *   big.jpg    19 KB -> NOTHING_RECEIVED
+ *
+ * 10 KB is far below any real photo, so this affected essentially every image
+ * attached by path — an ordinary JPEG, not just unusual formats.
+ *
+ * Scoped to images deliberately, and audio deserves spelling out because the
+ * reason is not the one it appears to be. An audio file's message contains only
+ * a metadata block — duration, codec, sample rate — on BOTH paths; no audio
+ * bytes are handed to the provider either way. Moving audio to the eager path
+ * would therefore change nothing about what the model receives. That audio
+ * content never reaches the model at all is a separate and pre-existing gap,
+ * not something this threshold decision can repair, and it is easy to mistake
+ * for working code because the metadata block answers exactly the questions
+ * ("how long is it?", "what sample rate?") a test is most tempted to ask.
+ * Video is left alone for the opposite reason: its frames are measurably
+ * present in the message and a model reads them correctly.
+ *
+ * Note this costs no extra memory: `tryRegisterFileReference` already calls
+ * `getFileBuffer()` and reads the whole file to register it. The lazy path was
+ * never lazy about reading — only about processing — so the difference here is
+ * simply whether the bytes survive.
+ */
+function isEagerMultimodalFile(file) {
+    if (typeof file === "string") {
+        return isImageLikeType(inferFileTypeFromExtension(file));
+    }
+    if (Buffer.isBuffer(file)) {
+        return isImageLikeType(inferFileTypeFromBuffer(file));
+    }
+    // A `FileWithMetadata` carries two independent declarations, and either one
+    // alone is enough: the shape exists for Slack/Curator-style uploads that
+    // arrive as bytes plus a mimetype, so its `filename` may be extensionless or
+    // simply wrong. Reading them as a `??` chain meant the first *recognised*
+    // name won outright — `upload.pdf` with `mimetype: "image/png"` classified as
+    // a PDF and lost its pixels down the lazy path. Any declaration of an image
+    // is therefore decisive.
+    const declared = [
+        inferFileTypeFromExtension(file.filename),
+        inferFileTypeFromMimetype(file.mimetype),
+    ];
+    if (declared.some(isImageLikeType)) {
+        return true;
+    }
+    // The buffer sniff is the last resort rather than a third vote, because it is
+    // a substring scan: an HTML page with an inline `<svg>` icon in its head
+    // would otherwise be pulled onto the eager path and sent in full, which is
+    // the opposite of what the size tiers are for. It only speaks when nothing
+    // else did.
+    return declared.every((type) => type === undefined)
+        ? isImageLikeType(inferFileTypeFromBuffer(file.buffer))
+        : false;
+}
+/**
+ * Whether a routing type should have its bytes preserved rather than previewed.
+ *
+ * "svg" is a separate routing type rather than a sub-case of "image" (it goes
+ * to the sanitizer, not to a vision encoder), but it is still an image as far
+ * as this decision is concerned: its markup IS its content, and previewing it
+ * away leaves the model with nothing. Accepting both keeps this correct
+ * whichever of the two type vocabularies the caller's map uses.
+ */
+function isImageLikeType(type) {
+    return type === "image" || type === "svg";
+}
+/**
+ * Infer a routing type from a caller-declared mimetype.
+ *
+ * Only images matter here — this exists so the eager/lazy decision can read a
+ * mimetype hint — and "application/octet-stream" is deliberately ignored,
+ * because it is the opaque sentinel a caller sends when it knows nothing, not
+ * a claim about content.
+ */
+function inferFileTypeFromMimetype(mimetype) {
+    if (!mimetype) {
+        return undefined;
+    }
+    const normalized = mimetype.split(";")[0].trim().toLowerCase();
+    if (normalized === "image/svg+xml") {
+        return "svg";
+    }
+    return normalized.startsWith("image/") ? "image" : undefined;
+}
 /**
  * Try to register a file with the FileReferenceRegistry for lazy processing.
  * Returns true if registration succeeded, false if it failed (caller should