@juspay/neurolink 9.94.2 → 9.94.4

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

@@ -34,6 +34,7 @@ export declare const ERROR_CODES: {
     readonly IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE";
     readonly IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL";
     readonly INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT";
+    readonly INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE";
     readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
     readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
     readonly RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT";
@@ -51,6 +52,10 @@ export declare const ERROR_CODES: {
     readonly INVALID_PPT_LOGO_PATH: "INVALID_PPT_LOGO_PATH";
     readonly INVALID_PPT_MODE: "INVALID_PPT_MODE";
     readonly INVALID_PPT_PROMPT: "INVALID_PPT_PROMPT";
+    readonly CSV_INVALID_INPUT: "CSV_INVALID_INPUT";
+    readonly CSV_ROW_INVALID: "CSV_ROW_INVALID";
+    readonly CSV_FILE_ACCESS_FAILED: "CSV_FILE_ACCESS_FAILED";
+    readonly CSV_PARSE_FAILED: "CSV_PARSE_FAILED";
 };
 /**
  * Enhanced error class with structured information
@@ -128,6 +133,25 @@ export declare class ErrorFactory {
      * Create an invalid configuration error (e.g., NaN for numeric values)
      */
     static invalidConfiguration(configName: string, reason: string, context?: Record<string, unknown>): NeuroLinkError;
+    /**
+     * Create an invalid CSV input error (e.g. an empty filePath/csvString argument).
+     */
+    static csvInvalidInput(message: string): NeuroLinkError;
+    /**
+     * Create a CSV row-shape violation error (#384) — a parsed row that isn't a
+     * string-keyed object with string values.
+     */
+    static csvRowInvalid(message: string, rowNumber: number): NeuroLinkError;
+    /**
+     * Create a CSV file access error (bad path, permissions, ENOENT/EACCES) (#375).
+     */
+    static csvFileAccessFailed(message: string, filePath: string, originalError?: Error): NeuroLinkError;
+    /**
+     * Create a CSV read/parse failure error (#375) — source stream errors and
+     * csv-parser errors both route through this, carrying the enriched
+     * `buildCsvParseErrorMessage` context in `message`.
+     */
+    static csvParseFailed(message: string, context: Record<string, unknown>, originalError?: Error): NeuroLinkError;
     /**
      * Create an invalid video resolution error
      */
@@ -176,6 +200,14 @@ export declare class ErrorFactory {
      * Create an image too large error
      */
     static imageTooLarge(sizeMB: string, maxMB: string): NeuroLinkError;
+    /**
+     * Create an invalid image size error (NaN/Infinity/negative byte length).
+     * Distinct from `imageTooLarge` — this rejects a malformed size value
+     * before it reaches the max-size comparison, since `NaN > maxSize` and
+     * `-1 > maxSize` both evaluate to `false` and would otherwise let a
+     * corrupted stat/header value silently skip the guard.
+     */
+    static invalidImageSize(size: number): NeuroLinkError;
     /**
      * Create an image too small error
      */

package/dist/lib/utils/errorHandling.js

@@ -45,6 +45,7 @@ export const ERROR_CODES = {
     IMAGE_TOO_LARGE: "IMAGE_TOO_LARGE",
     IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL",
     INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT",
+    INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE",
     // PDF validation errors
     PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
     // Rate limiter errors
@@ -66,6 +67,11 @@ export const ERROR_CODES = {
     INVALID_PPT_LOGO_PATH: "INVALID_PPT_LOGO_PATH",
     INVALID_PPT_MODE: "INVALID_PPT_MODE",
     INVALID_PPT_PROMPT: "INVALID_PPT_PROMPT",
+    // CSV validation/parsing errors (#1199)
+    CSV_INVALID_INPUT: "CSV_INVALID_INPUT",
+    CSV_ROW_INVALID: "CSV_ROW_INVALID",
+    CSV_FILE_ACCESS_FAILED: "CSV_FILE_ACCESS_FAILED",
+    CSV_PARSE_FAILED: "CSV_PARSE_FAILED",
 };
 /**
  * Enhanced error class with structured information
@@ -259,6 +265,66 @@ export class ErrorFactory {
         });
     }
     // ============================================================================
+    // CSV VALIDATION/PARSING ERRORS (#1199)
+    // ============================================================================
+    /**
+     * Create an invalid CSV input error (e.g. an empty filePath/csvString argument).
+     */
+    static csvInvalidInput(message) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.CSV_INVALID_INPUT,
+            message,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {},
+        });
+    }
+    /**
+     * Create a CSV row-shape violation error (#384) — a parsed row that isn't a
+     * string-keyed object with string values.
+     */
+    static csvRowInvalid(message, rowNumber) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.CSV_ROW_INVALID,
+            message,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { rowNumber },
+        });
+    }
+    /**
+     * Create a CSV file access error (bad path, permissions, ENOENT/EACCES) (#375).
+     */
+    static csvFileAccessFailed(message, filePath, originalError) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.CSV_FILE_ACCESS_FAILED,
+            message,
+            category: ErrorCategory.RESOURCE,
+            severity: ErrorSeverity.HIGH,
+            retriable: false,
+            context: { filePath },
+            originalError,
+        });
+    }
+    /**
+     * Create a CSV read/parse failure error (#375) — source stream errors and
+     * csv-parser errors both route through this, carrying the enriched
+     * `buildCsvParseErrorMessage` context in `message`.
+     */
+    static csvParseFailed(message, context, originalError) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.CSV_PARSE_FAILED,
+            message,
+            category: ErrorCategory.EXECUTION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context,
+            originalError,
+        });
+    }
+    // ============================================================================
     // VIDEO VALIDATION ERRORS
     // ============================================================================
     /**
@@ -505,6 +571,26 @@ export class ErrorFactory {
             },
         });
     }
+    /**
+     * Create an invalid image size error (NaN/Infinity/negative byte length).
+     * Distinct from `imageTooLarge` — this rejects a malformed size value
+     * before it reaches the max-size comparison, since `NaN > maxSize` and
+     * `-1 > maxSize` both evaluate to `false` and would otherwise let a
+     * corrupted stat/header value silently skip the guard.
+     */
+    static invalidImageSize(size) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.INVALID_IMAGE_SIZE,
+            message: `Invalid image size: ${size} (must be a finite, non-negative number)`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: {
+                field: "input.images",
+                size,
+            },
+        });
+    }
     /**
      * Create an image too small error
      */

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

@@ -59,9 +59,41 @@ export declare class ImageProcessor {
      */
     static detectImageType(input: string | Buffer): string;
     /**
-     * Validate image size (default 10MB limit)
+     * Throwing size guard for a raw byte length. Prevents memory exhaustion by
+     * rejecting an oversized input BEFORE an unbounded read/allocation happens
+     * (#257) — callers that can get a size cheaply (e.g. `fs.stat`) should
+     * validate it before ever reading the bytes into memory. Default limit is
+     * the canonical `SIZE_LIMITS_BYTES.IMAGE_MAX` (10 MB); there is no public
+     * way to raise it — `maxSize` is an internal-only override for advanced
+     * callers (e.g. video image inputs use a higher limit).
+     *
+     * @param size - Byte length to validate
+     * @param context - Short label identifying the source (unused in the
+     *   thrown message today, kept for call-site readability and future use)
+     * @param maxSize - Max allowed size in bytes
+     * @throws NeuroLinkError (`INVALID_IMAGE_SIZE`) if `size` is not a finite,
+     *   non-negative number
+     * @throws NeuroLinkError (`IMAGE_TOO_LARGE`) if `size` exceeds `maxSize`
+     */
+    static validateSize(size: number, context: string, maxSize?: number): void;
+    /**
+     * Throwing size guard for image buffers. Prevents memory exhaustion by
+     * rejecting oversized buffers with a descriptive error BEFORE an unbounded
+     * `Buffer.toString("base64")` allocation (#257). Delegates to
+     * `validateSize` so buffer-based and pre-read (stat-based) callers share
+     * one implementation.
+     *
+     * @param buffer - Image buffer to validate
+     * @param context - Short label identifying the source (see `validateSize`)
+     * @param maxSize - Max allowed size in bytes
+     * @throws NeuroLinkError (`IMAGE_TOO_LARGE`) if the buffer exceeds `maxSize`
+     */
+    static validateBufferSize(buffer: Buffer, context: string, maxSize?: number): void;
+    /**
+     * Size-guarded Buffer → base64. Use in place of `buffer.toString("base64")`
+     * on any path that converts a caller-supplied image buffer (#257).
      */
-    static validateImageSize(data: Buffer | string, maxSize?: number): boolean;
+    static safeBase64Convert(buffer: Buffer, context: string, maxSize?: number): string;
     /**
      * Validate image format
      */
@@ -126,9 +158,15 @@ export declare const imageUtils: {
      */
     formatFileSize: (bytes: number) => string;
     /**
-     * Convert Buffer to base64 string
+     * Convert Buffer to base64 string. Guarded by the same #257 size limit as
+     * every other conversion site (default `SIZE_LIMITS_BYTES.IMAGE_MAX`);
+     * pass `maxBytes` to override for a caller with a legitimate need for a
+     * different ceiling rather than silently accepting an unbounded buffer.
+     * `imageUtils`/`ImageProcessor` are internal-only — not re-exported from
+     * `src/lib/index.ts` or the package's public `exports` map — so this
+     * default does not change behavior for any external SDK consumer.
      */
-    bufferToBase64: (buffer: Buffer) => string;
+    bufferToBase64: (buffer: Buffer, maxBytes?: number) => string;
     /**
      * Convert base64 string to Buffer
      */

package/dist/lib/utils/imageProcessor.js

@@ -6,7 +6,9 @@ import { logger } from "./logger.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
 import { withRetry } from "./retryHandler.js";
 import { SYSTEM_LIMITS } from "../core/constants.js";
+import { SIZE_LIMITS_BYTES } from "../processors/config/sizeLimits.js";
 import { getImageCache } from "./imageCache.js";
+import { ErrorFactory, NeuroLinkError } from "./errorHandling.js";
 /**
  * Network error codes that should trigger a retry
  */
@@ -75,7 +77,7 @@ export class ImageProcessor {
             throw new Error("Invalid image processing: buffer is empty");
         }
         const mediaType = this.detectImageType(content);
-        const base64 = content.toString("base64");
+        const base64 = ImageProcessor.safeBase64Convert(content, "image processing");
         const dataUri = `data:${mediaType};base64,${base64}`;
         // Validate output before returning
         this.validateProcessOutput(dataUri, base64, mediaType);
@@ -138,10 +140,15 @@ export class ImageProcessor {
                 return `data:image/jpeg;base64,${image}`;
             }
             // Handle Buffer - convert to data URI
-            const base64 = image.toString("base64");
+            const base64 = ImageProcessor.safeBase64Convert(image, "OpenAI image input");
             return `data:image/jpeg;base64,${base64}`;
         }
         catch (error) {
+            // Preserve typed errors (e.g. IMAGE_TOO_LARGE) as-is — don't flatten
+            // them into a generic Error and lose the error `code` for callers.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error("Failed to process image for OpenAI:", error);
             throw new Error(`Image processing failed for OpenAI: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -170,7 +177,7 @@ export class ImageProcessor {
                 }
             }
             else {
-                base64Data = image.toString("base64");
+                base64Data = ImageProcessor.safeBase64Convert(image, "provider image input");
             }
             return {
                 mimeType,
@@ -178,6 +185,11 @@ export class ImageProcessor {
             };
         }
         catch (error) {
+            // Preserve typed errors (e.g. IMAGE_TOO_LARGE) as-is — don't flatten
+            // them into a generic Error and lose the error `code` for callers.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error("Failed to process image for Google AI:", error);
             throw new Error(`Image processing failed for Google AI: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -206,7 +218,7 @@ export class ImageProcessor {
                 }
             }
             else {
-                base64Data = image.toString("base64");
+                base64Data = ImageProcessor.safeBase64Convert(image, "provider image input");
             }
             return {
                 mediaType,
@@ -214,6 +226,11 @@ export class ImageProcessor {
             };
         }
         catch (error) {
+            // Preserve typed errors (e.g. IMAGE_TOO_LARGE) as-is — don't flatten
+            // them into a generic Error and lose the error `code` for callers.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error("Failed to process image for Anthropic:", error);
             throw new Error(`Image processing failed for Anthropic: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -238,6 +255,11 @@ export class ImageProcessor {
             }
         }
         catch (error) {
+            // Preserve typed errors bubbling up from processImageForGoogle/
+            // processImageForAnthropic (e.g. IMAGE_TOO_LARGE) as-is.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error("Failed to process image for Vertex AI:", error);
             throw new Error(`Image processing failed for Vertex AI: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -322,20 +344,64 @@ export class ImageProcessor {
         }
     }
     /**
-     * Validate image size (default 10MB limit)
+     * Throwing size guard for a raw byte length. Prevents memory exhaustion by
+     * rejecting an oversized input BEFORE an unbounded read/allocation happens
+     * (#257) — callers that can get a size cheaply (e.g. `fs.stat`) should
+     * validate it before ever reading the bytes into memory. Default limit is
+     * the canonical `SIZE_LIMITS_BYTES.IMAGE_MAX` (10 MB); there is no public
+     * way to raise it — `maxSize` is an internal-only override for advanced
+     * callers (e.g. video image inputs use a higher limit).
+     *
+     * @param size - Byte length to validate
+     * @param context - Short label identifying the source (unused in the
+     *   thrown message today, kept for call-site readability and future use)
+     * @param maxSize - Max allowed size in bytes
+     * @throws NeuroLinkError (`INVALID_IMAGE_SIZE`) if `size` is not a finite,
+     *   non-negative number
+     * @throws NeuroLinkError (`IMAGE_TOO_LARGE`) if `size` exceeds `maxSize`
      */
-    static validateImageSize(data, maxSize = 10 * 1024 * 1024) {
-        try {
-            const size = typeof data === "string"
-                ? Buffer.byteLength(data, "base64")
-                : data.length;
-            return size <= maxSize;
-        }
-        catch (error) {
-            logger.warn("Failed to validate image size:", error);
-            return false;
+    static validateSize(size, context, maxSize = SIZE_LIMITS_BYTES.IMAGE_MAX) {
+        // Reject a malformed maxSize before it's ever compared: `size > NaN` and
+        // `size > Infinity` (for a negative maxSize) can both evaluate `false`,
+        // which would let a corrupted/negative limit bypass the guard entirely.
+        if (!Number.isFinite(maxSize) || maxSize < 0) {
+            throw ErrorFactory.invalidConfiguration("maxSize", "must be a finite, non-negative byte count", { maxSize, context });
+        }
+        // Fail closed on malformed sizes first: `NaN > maxSize` and
+        // `-1 > maxSize` both evaluate to `false`, which would otherwise let a
+        // corrupted stat/header value silently skip the guard below.
+        if (!Number.isFinite(size) || size < 0) {
+            throw ErrorFactory.invalidImageSize(size);
+        }
+        if (size > maxSize) {
+            const mb = (size / (1024 * 1024)).toFixed(1);
+            const maxMb = (maxSize / (1024 * 1024)).toFixed(0);
+            throw ErrorFactory.imageTooLarge(mb, maxMb);
         }
     }
+    /**
+     * Throwing size guard for image buffers. Prevents memory exhaustion by
+     * rejecting oversized buffers with a descriptive error BEFORE an unbounded
+     * `Buffer.toString("base64")` allocation (#257). Delegates to
+     * `validateSize` so buffer-based and pre-read (stat-based) callers share
+     * one implementation.
+     *
+     * @param buffer - Image buffer to validate
+     * @param context - Short label identifying the source (see `validateSize`)
+     * @param maxSize - Max allowed size in bytes
+     * @throws NeuroLinkError (`IMAGE_TOO_LARGE`) if the buffer exceeds `maxSize`
+     */
+    static validateBufferSize(buffer, context, maxSize = SIZE_LIMITS_BYTES.IMAGE_MAX) {
+        ImageProcessor.validateSize(buffer.length, context, maxSize);
+    }
+    /**
+     * Size-guarded Buffer → base64. Use in place of `buffer.toString("base64")`
+     * on any path that converts a caller-supplied image buffer (#257).
+     */
+    static safeBase64Convert(buffer, context, maxSize = SIZE_LIMITS_BYTES.IMAGE_MAX) {
+        ImageProcessor.validateBufferSize(buffer, context, maxSize);
+        return buffer.toString("base64");
+    }
     /**
      * Validate image format
      */
@@ -467,7 +533,7 @@ export class ImageProcessor {
                             : image;
                     }
                     else {
-                        data = image.toString("base64");
+                        data = ImageProcessor.safeBase64Convert(image, "image input");
                     }
                     format = "base64";
             }
@@ -479,6 +545,11 @@ export class ImageProcessor {
             };
         }
         catch (error) {
+            // Preserve typed errors (e.g. IMAGE_TOO_LARGE) bubbling up from the
+            // provider-specific branches above as-is.
+            if (error instanceof NeuroLinkError) {
+                throw error;
+            }
             logger.error(`Failed to process image for ${provider}:`, error);
             throw new Error(`Image processing failed: ${error instanceof Error ? error.message : "Unknown error"}`, { cause: error });
         }
@@ -597,10 +668,16 @@ export const imageUtils = {
         return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
     },
     /**
-     * Convert Buffer to base64 string
+     * Convert Buffer to base64 string. Guarded by the same #257 size limit as
+     * every other conversion site (default `SIZE_LIMITS_BYTES.IMAGE_MAX`);
+     * pass `maxBytes` to override for a caller with a legitimate need for a
+     * different ceiling rather than silently accepting an unbounded buffer.
+     * `imageUtils`/`ImageProcessor` are internal-only — not re-exported from
+     * `src/lib/index.ts` or the package's public `exports` map — so this
+     * default does not change behavior for any external SDK consumer.
      */
-    bufferToBase64: (buffer) => {
-        return buffer.toString("base64");
+    bufferToBase64: (buffer, maxBytes = SIZE_LIMITS_BYTES.IMAGE_MAX) => {
+        return ImageProcessor.safeBase64Convert(buffer, "buffer-to-base64", maxBytes);
     },
     /**
      * Convert base64 string to Buffer

package/dist/lib/utils/messageBuilder.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync, statSync } from "fs";
+import { readFile as readFileAsync, stat as statAsync } from "fs/promises";
 import { getGlobalDispatcher, interceptors, request } from "undici";
 import { MultimodalLogger, ProviderImageAdapter, } from "../adapters/providerImageAdapter.js";
 import { CONVERSATION_INSTRUCTIONS, STRUCTURED_OUTPUT_INSTRUCTIONS, } from "../config/conversationMemory.js";
@@ -6,8 +7,10 @@ import { getAvailableInputTokens } from "../constants/contextWindows.js";
 import { enforceAggregateFileBudget, FILE_READ_BUDGET_PERCENT, } from "../context/fileTokenBudget.js";
 import { SIZE_TIER_THRESHOLDS } from "../types/index.js";
 import { tracers, ATTR, withSpan } from "../telemetry/index.js";
+import { NeuroLinkError } from "./errorHandling.js";
 import { FileDetector } from "./fileDetector.js";
 import { getImageCache } from "./imageCache.js";
+import { ImageProcessor } from "./imageProcessor.js";
 import { logger } from "./logger.js";
 import { PDFImageConverter, PDFProcessor } from "./pdfProcessor.js";
 import { urlDownloadRateLimiter } from "./rateLimiter.js";
@@ -1396,13 +1399,38 @@ function detectMimeTypeFromBuffer(buffer) {
 /**
  * Convert file path to raw base64 string.
  * Returns raw base64 (not a data: URI) to avoid SSRF validation in AI SDK v6.
+ * Uses async fs so a large/slow-filesystem image never blocks the event loop
+ * while the size guard (below) or the read itself is in flight.
  */
-function convertFilePathToBase64(filePath) {
-    if (!existsSync(filePath)) {
-        throw new Error(`Image file not found: ${filePath}`);
+async function convertFilePathToBase64(filePath) {
+    let stats;
+    try {
+        stats = await statAsync(filePath);
     }
-    const buffer = readFileSync(filePath);
-    return buffer.toString("base64");
+    catch (error) {
+        // Only ENOENT means "not found" — EACCES/ELOOP/etc. are real access or
+        // filesystem problems that must not be misreported as a missing file.
+        const code = error instanceof Error
+            ? error.code
+            : undefined;
+        if (code === "ENOENT") {
+            throw new Error(`Image file not found: ${filePath}`, { cause: error });
+        }
+        throw new Error(`Cannot access image file ${filePath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (!stats.isFile()) {
+        throw new Error(`Image path is not a file: ${filePath}`);
+    }
+    // #257: check the file size via stat BEFORE reading it into memory, so a
+    // huge image path never triggers an unbounded read + base64 allocation.
+    // Delegates to ImageProcessor's shared guard (no local reimplementation).
+    const context = `image file "${filePath}"`;
+    ImageProcessor.validateSize(stats.size, context);
+    const buffer = await readFileAsync(filePath);
+    // TOCTOU: the file can grow, or a symlink can be swapped, between the stat
+    // above and this read completing. Re-validate the bytes actually read
+    // (not just the pre-read stat) before the base64 allocation.
+    return ImageProcessor.safeBase64Convert(buffer, context);
 }
 /**
  * Process a single image input and convert to raw base64 format.
@@ -1413,7 +1441,7 @@ function convertFilePathToBase64(filePath) {
  * Passing raw base64 avoids this because `new URL(base64string)` throws and
  * the SDK treats the string as inline base64 data instead.
  */
-function processImageToBase64(image, index) {
+async function processImageToBase64(image, index) {
     let imageData;
     let mimeType = "image/jpeg"; // Default mime type
     if (typeof image === "string") {
@@ -1444,7 +1472,7 @@ function processImageToBase64(image, index) {
         else {
             // File path string - convert to raw base64
             try {
-                imageData = convertFilePathToBase64(image);
+                imageData = await convertFilePathToBase64(image);
                 mimeType = getMimeTypeFromExtension(image);
             }
             catch (error) {
@@ -1452,6 +1480,11 @@ function processImageToBase64(image, index) {
                     index,
                     filePath: image,
                 });
+                // Preserve typed errors (e.g. IMAGE_TOO_LARGE) as-is — don't flatten
+                // them into a generic Error and lose the error `code` for callers.
+                if (error instanceof NeuroLinkError) {
+                    throw error;
+                }
                 throw new Error(`Failed to convert file path to base64: ${image}. ${error}`, { cause: error });
             }
         }
@@ -1462,6 +1495,9 @@ function processImageToBase64(image, index) {
         if (detectedMimeType) {
             mimeType = detectedMimeType;
         }
+        // #257: guard the buffer size before the unbounded base64 conversion.
+        // Delegates to ImageProcessor's shared guard (no local reimplementation).
+        ImageProcessor.validateBufferSize(image, `image input at index ${index}`);
         imageData = image.toString("base64");
     }
     return { imageData, mimeType };
@@ -1524,11 +1560,13 @@ async function convertSimpleImagesToProviderFormat(text, images, provider, _mode
     const content = [
         { type: "text", text: enhancedText },
     ];
-    // Process all images (including downloaded URLs) for Vercel AI SDK
-    actualImages.forEach(({ data: image }, index) => {
+    // Process all images (including downloaded URLs) for Vercel AI SDK.
+    // Sequential for...of (not Promise.all) to preserve image ordering and
+    // keep the original forEach's one-at-a-time error semantics.
+    for (const [index, { data: image }] of actualImages.entries()) {
         try {
             // Use helper function to process image and reduce nesting depth
-            const { imageData, mimeType } = processImageToBase64(image, index);
+            const { imageData, mimeType } = await processImageToBase64(image, index);
             content.push({
                 type: "image",
                 image: imageData,
@@ -1542,7 +1580,7 @@ async function convertSimpleImagesToProviderFormat(text, images, provider, _mode
             });
             throw error;
         }
-    });
+    }
     return content;
 }
 /**

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

@@ -50,11 +50,7 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
         csvFiles: (string | Buffer<ArrayBufferLike>)[] | undefined;
         pdfFiles: (string | Buffer<ArrayBufferLike>)[] | undefined;
     };
-    csvOptions: {
-        maxRows?: number;
-        formatStyle?: "raw" | "markdown" | "json";
-        includeHeaders?: boolean;
-    } | undefined;
+    csvOptions: import("../types/file.js").CSVProcessorOptions | undefined;
     systemPrompt: string | undefined;
     conversationHistory: import("../types/conversation.js").ChatMessage[] | undefined;
     provider: string;

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

@@ -0,0 +1,25 @@
+/**
+ * Buffer → string decoding with encoding detection (#362).
+ *
+ * Order of resolution:
+ *   1. Explicit override (any iconv-lite label).
+ *   2. Deterministic BOM sniff (UTF-8 / UTF-16 LE / UTF-16 BE).
+ *   3. `chardet` statistical detection, mapped to an iconv-lite label.
+ *   4. Fallback to UTF-8 (preserves the historical hard-coded default).
+ *
+ * Decoding always goes through `iconv-lite`, and any residual BOM is stripped
+ * from the decoded string so it can't glue onto the first token.
+ */
+import type { DecodedBuffer } from "../types/index.js";
+/** Strip a leading BOM (U+FEFF) from an already-decoded string. */
+export declare function stripBomString(text: string): string;
+/**
+ * Decode a buffer to text, detecting the encoding unless overridden.
+ *
+ * @param isCompleteBuffer - Whether `buffer` is the entire source (default
+ *   `true`). Pass `false` when `buffer` is only a peeked prefix (e.g. a
+ *   streaming head-sniff) — the ASCII fast path still commits to "utf-8" for
+ *   the peeked bytes (unchanged behavior), but reports a lower confidence
+ *   since later bytes not yet seen could still be non-ASCII (#1199).
+ */
+export declare function decodeBuffer(buffer: Buffer, override?: string, isCompleteBuffer?: boolean): DecodedBuffer;