@juspay/neurolink 10.10.7 → 10.10.9

package/dist/types/stream.d.ts

@@ -225,11 +225,26 @@ export type StreamOptions = {
         password?: string;
         /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
         maxCanvasPixels?: number;
+        /**
+         * Render scale for the image fallback used by providers without native PDF
+         * support (#297). Higher is sharper but costs roughly the square in memory
+         * and tokens. Range 0.1-10; defaults to PDF_LIMITS.DEFAULT_SCALE (1.5).
+         */
+        scale?: number;
+        /**
+         * Max pages converted by the image fallback (#297). Pages beyond this are
+         * not sent to the model at all. Defaults to PDF_LIMITS.DEFAULT_MAX_PAGES (20).
+         */
+        maxPages?: number;
     };
     videoOptions?: {
+        /** Frames to extract. Unset lets VideoProcessor pick from the clip's duration; clamped to 100. */
         frames?: number;
+        /** Frame encoder quality, clamped to 1-100. Default 80. */
         quality?: number;
+        /** Frame encoding. Default jpeg. */
         format?: "jpeg" | "png";
+        /** Not implemented yet (#433) — warns rather than silently doing nothing. */
         transcribeAudio?: boolean;
     };
     /**

package/dist/utils/errorHandling.d.ts

@@ -39,6 +39,9 @@ export declare const ERROR_CODES: {
     readonly FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED";
     readonly CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED";
     readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
+    readonly PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED: "PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED";
+    readonly PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED: "PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED";
+    readonly PDF_PAGE_COUNT_UNVERIFIABLE: "PDF_PAGE_COUNT_UNVERIFIABLE";
     readonly PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED";
     readonly PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD";
     readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
@@ -203,6 +206,24 @@ export declare class ErrorFactory {
      * Create a PDF page limit exceeded error
      */
     static pdfPageLimitExceeded(estimatedPages: number, maxPages: number, provider: string): NeuroLinkError;
+    /**
+     * The combined page count across every PDF in one request exceeds what the
+     * provider accepts (#309). Distinct from `pdfPageLimitExceeded`, which is
+     * per-file — here each document can be individually legal.
+     */
+    static pdfAggregatePageLimitExceeded(fileCount: number, totalPages: number, maxPages: number, provider: string): NeuroLinkError;
+    /**
+     * The combined byte size across every PDF in one request exceeds what the
+     * provider accepts (#309).
+     */
+    static pdfAggregateSizeLimitExceeded(fileCount: number, totalMB: number, maxSizeMB: number, provider: string): NeuroLinkError;
+    /**
+     * A PDF supplied through the untrusted `input.content` surface could not be
+     * parsed for a page count (#309). Caller-supplied `metadata.pages` is not
+     * authoritative there, so an unreadable document is rejected rather than
+     * admitted with an assumed count of zero.
+     */
+    static pdfPageCountUnverifiable(filenames: string[], provider: string): NeuroLinkError;
     /**
      * The PDF is encrypted and no password was supplied (#258).
      */

package/dist/utils/errorHandling.js

@@ -52,6 +52,9 @@ export const ERROR_CODES = {
     CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED",
     // PDF validation errors
     PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
+    PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED: "PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED",
+    PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED: "PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED",
+    PDF_PAGE_COUNT_UNVERIFIABLE: "PDF_PAGE_COUNT_UNVERIFIABLE",
     PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED",
     PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD",
     // Rate limiter errors
@@ -557,6 +560,56 @@ export class ErrorFactory {
             },
         });
     }
+    /**
+     * The combined page count across every PDF in one request exceeds what the
+     * provider accepts (#309). Distinct from `pdfPageLimitExceeded`, which is
+     * per-file — here each document can be individually legal.
+     */
+    static pdfAggregatePageLimitExceeded(fileCount, totalPages, maxPages, provider) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED,
+            message: `[PDF] Combined page count across ${fileCount} PDF(s) (${totalPages}) exceeds the ` +
+                `${maxPages}-page limit for ${provider}. ` +
+                `Split the request or reduce the number of PDFs.`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { fileCount, totalPages, maxPages, provider },
+        });
+    }
+    /**
+     * The combined byte size across every PDF in one request exceeds what the
+     * provider accepts (#309).
+     */
+    static pdfAggregateSizeLimitExceeded(fileCount, totalMB, maxSizeMB, provider) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED,
+            message: `[PDF] Combined size across ${fileCount} PDF(s) (${totalMB.toFixed(2)}MB) exceeds the ` +
+                `${maxSizeMB}MB limit for ${provider}.`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { fileCount, totalMB, maxSizeMB, provider },
+        });
+    }
+    /**
+     * A PDF supplied through the untrusted `input.content` surface could not be
+     * parsed for a page count (#309). Caller-supplied `metadata.pages` is not
+     * authoritative there, so an unreadable document is rejected rather than
+     * admitted with an assumed count of zero.
+     */
+    static pdfPageCountUnverifiable(filenames, provider) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_PAGE_COUNT_UNVERIFIABLE,
+            message: `[PDF] Cannot verify the page count for ${filenames.length} PDF(s) supplied via ` +
+                `input.content (${filenames.join(", ")}). Provide readable PDFs, or submit them ` +
+                `via input.pdfFiles where page counts are derived during detection.`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { filenames, provider },
+        });
+    }
     /**
      * The PDF is encrypted and no password was supplied (#258).
      */

package/dist/utils/fileDetector.js

@@ -344,13 +344,13 @@ export class FileDetector {
                 logger.warn(`[FileDetector] All fallback parsing failed for type "${detection.type}". ` +
                     `Attempted: ${options.allowedTypes.join(", ")}. Falling through to universal handler.`);
                 const csvOptions = options?.csvOptions;
-                const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider);
+                const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider, options?.videoOptions);
                 FileDetector.setFileResultSpanAttributes(span, result, inputFilename, detection.type);
                 return result;
             }
             const content = await FileDetector.loadContent(input, detection, options);
             const csvOptions = options?.csvOptions;
-            const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider);
+            const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider, options?.videoOptions);
             FileDetector.setFileResultSpanAttributes(span, result, inputFilename, detection.type);
             return result;
         });
@@ -967,7 +967,7 @@ export class FileDetector {
     /**
      * Route to appropriate processor
      */
-    static async processFile(content, detection, options, provider) {
+    static async processFile(content, detection, options, provider, videoOptions) {
         switch (detection.type) {
             case "csv":
                 // Pass original extension through to CSV processor; if detection has none,
@@ -985,7 +985,7 @@ export class FileDetector {
                 // AI providers don't support SVG as image format, so we extract text content
                 return await FileDetector.processSvgAsText(content, detection);
             case "video":
-                return await FileDetector.processVideoFile(content, detection);
+                return await FileDetector.processVideoFile(content, detection, videoOptions);
             case "audio":
                 return await FileDetector.processAudioFile(content, detection);
             case "archive":
@@ -1031,7 +1031,7 @@ export class FileDetector {
     /**
      * Process video file: extract metadata, keyframes, and subtitles via VideoProcessor
      */
-    static async processVideoFile(content, detection) {
+    static async processVideoFile(content, detection, videoOptions) {
         const videoFilename = detection.metadata.filename || "video";
         try {
             const videoResult = await (await getVideoProcessor()).processFile({
@@ -1040,7 +1040,10 @@ export class FileDetector {
                 mimetype: detection.mimeType || "video/mp4",
                 size: content.length,
                 buffer: content,
-            });
+            }, 
+            // #478: carry the caller's keyframe budget/quality/format through to
+            // the processor; previously these stopped at the CLI layer.
+            videoOptions);
             if (videoResult.success && videoResult.data) {
                 return {
                     type: "video",

package/dist/utils/messageBuilder.js

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync, statSync } from "fs";
 import { readFile as readFileAsync, stat as statAsync } from "fs/promises";
-import { basename } from "path";
 import { getGlobalDispatcher, interceptors, request } from "undici";
 import { MultimodalLogger, ProviderImageAdapter, } from "../adapters/providerImageAdapter.js";
 import { CONVERSATION_INSTRUCTIONS, STRUCTURED_OUTPUT_INSTRUCTIONS, } from "../config/conversationMemory.js";
 import { getAvailableInputTokens } from "../constants/contextWindows.js";
+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";
@@ -809,6 +809,20 @@ export function mergeMediaFileAliases(input) {
     input.audioFiles = undefined;
     input.videoFiles = undefined;
 }
+/**
+ * #478: `transcribeAudio` (CLI `--transcribe-audio`) is accepted by the options
+ * surface but no video-audio transcription exists yet — VideoProcessor extracts
+ * keyframes and embedded subtitle tracks only, and the transcription step is
+ * still open as #433. Say so once per request rather than letting the caller
+ * believe a transcript was produced and silently omitted.
+ */
+function warnIfVideoTranscriptionRequested(videoOptions) {
+    if (videoOptions?.transcribeAudio) {
+        logger.warn("[NEUROLINK] Video audio transcription was requested but is not implemented yet " +
+            "(tracked as #433). Keyframes and any embedded subtitle tracks are still extracted; " +
+            "spoken audio will not be transcribed.");
+    }
+}
 /**
  * Process the unified files array with auto-detection.
  * Handles lazy file registration, full processing, and preview injection.
@@ -825,6 +839,7 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
     }
     const totalFiles = options.input.files.length;
     const files = options.input.files;
+    warnIfVideoTranscriptionRequested(options.videoOptions);
     return withSpan({
         name: "neurolink.file.process_all",
         tracer: tracers.file,
@@ -882,6 +897,15 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
                         "unknown",
                     ],
                     csvOptions: options.csvOptions,
+                    // #478: videos arrive through this unified `files` path, so this is
+                    // where the CLI's frame/quality/format request has to be handed on.
+                    videoOptions: options.videoOptions
+                        ? {
+                            frames: options.videoOptions.frames,
+                            quality: options.videoOptions.quality,
+                            format: options.videoOptions.format,
+                        }
+                        : undefined,
                     provider: provider,
                     mimetypeHint: fileMimetypeHint,
                 });
@@ -1020,6 +1044,83 @@ function enforcePostProcessingBudget(options, provider, model) {
         `budget=${contextWindow.toLocaleString()} tokens, ` +
         `utilization=${contextWindow > 0 ? ((totalContentTokens / contextWindow) * 100).toFixed(1) : "N/A"}%`);
 }
+/**
+ * #309: enforce the provider's page/size ceilings across ALL PDFs in a request,
+ * not just per-file. N files each just under the single-file limit can still
+ * blow past it in aggregate (e.g. three 40-page PDFs → 120 pages for a
+ * 100-page API).
+ *
+ * Shared by both PDF submission surfaces: `input.pdfFiles` (via
+ * `processExplicitPdfFiles`) and `input.content` with `type: "pdf"` (via
+ * `convertContentToProviderFormat`). The latter previously built its own
+ * `pdfFiles` array and reached the provider without ever calling this guard,
+ * so the limit was bypassable by moving the same payload to `input.content`.
+ */
+/**
+ * Basename that strips BOTH separators regardless of host platform.
+ *
+ * `path.basename` only understands the host's separator, so on a POSIX server
+ * a Windows-style filename (`C:\Users\alice\q3-merger.pdf`) comes back
+ * completely unchanged — defeating the point of trimming it before it reaches
+ * a log line, since caller-controlled paths can carry usernames and internal
+ * directory structure.
+ */
+function safeBasename(filename) {
+    const lastSeparator = Math.max(filename.lastIndexOf("/"), filename.lastIndexOf("\\"));
+    const trimmed = lastSeparator === -1 ? filename : filename.slice(lastSeparator + 1);
+    return trimmed || "<unnamed file>";
+}
+async function enforceAggregatePdfLimits(pdfFiles, provider, { trustSuppliedPageCounts }) {
+    const aggregateConfig = PDFProcessor.getProviderConfig(provider);
+    // Only an empty set is exempt. A single PDF must still be checked: on the
+    // `input.content` path nothing else validates it (that path never goes
+    // through FileDetector.detectAndProcess / PDFProcessor.process), so bailing
+    // at length <= 1 let one 200-page document through untouched.
+    if (!aggregateConfig || pdfFiles.length === 0) {
+        return;
+    }
+    // Byte total is free to compute — enforce it BEFORE parsing anything, so an
+    // oversized request is rejected without first spending parser CPU/memory on
+    // every document in it.
+    const totalMB = pdfFiles.reduce((sum, f) => sum + f.buffer.length, 0) / (1024 * 1024);
+    if (totalMB > aggregateConfig.maxSizeMB) {
+        throw ErrorFactory.pdfAggregateSizeLimitExceeded(pdfFiles.length, totalMB, aggregateConfig.maxSizeMB, provider);
+    }
+    // `trustSuppliedPageCounts` is the difference between the two surfaces.
+    // On `input.pdfFiles` the count comes from FileDetector's own detection, so
+    // it is authoritative. On `input.content` it is `metadata.pages` — plain
+    // caller input — and trusting it lets a request declare `pages: 1` for each
+    // of three 40-page PDFs and sail past the ceiling. There, the count is
+    // always re-derived from the bytes and the supplied value is ignored.
+    const pageCounts = await Promise.all(pdfFiles.map(async (f) => trustSuppliedPageCounts && typeof f.pageCount === "number"
+        ? f.pageCount
+        : await PDFProcessor.resolvePageCount(f.buffer)));
+    // Filenames are caller-controlled and may be full paths carrying
+    // PII/internal directory segments — surface only the basename, stripping
+    // both separators so a Windows path is trimmed on a POSIX host too.
+    const unknownFileNames = pdfFiles
+        .filter((_, i) => typeof pageCounts[i] !== "number")
+        .map((f) => (f.filename ? safeBasename(f.filename) : "<unnamed file>"));
+    const totalPages = pageCounts.reduce((sum, p) => sum + (typeof p === "number" ? p : 0), 0);
+    if (unknownFileNames.length > 0) {
+        if (!trustSuppliedPageCounts) {
+            // Untrusted surface: an unreadable count is indistinguishable from an
+            // evasion attempt, and counting it as zero is precisely the hole. Fail
+            // closed rather than admit an unverifiable document.
+            throw ErrorFactory.pdfPageCountUnverifiable(unknownFileNames, provider);
+        }
+        // Trusted surface: detection already vetted these, so one unreadable
+        // count must not fail an otherwise valid request — but it must not be
+        // silent either, since the known sum may undercount the true total.
+        logger.warn(`[PDF] Aggregate page-limit check across ${pdfFiles.length} PDFs could only be ` +
+            `partially verified: ${unknownFileNames.length} file(s) have an unknown ` +
+            `page count (${unknownFileNames.join(", ")}), so the known total (${totalPages}) may ` +
+            `undercount the true combined page count.`);
+    }
+    if (totalPages > aggregateConfig.maxPages) {
+        throw ErrorFactory.pdfAggregatePageLimitExceeded(pdfFiles.length, totalPages, aggregateConfig.maxPages, provider);
+    }
+}
 /**
  * Process explicit PDF files and return structured PDF entries for multimodal processing.
  */
@@ -1050,6 +1151,10 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
                     // #260: carry the per-page canvas-pixel ceiling so the caller can
                     // raise (or lower) the memory guard for the image-fallback render.
                     maxCanvasPixels: options.pdfOptions?.maxCanvasPixels,
+                    // #297: render scale / page ceiling, so the lowered default is
+                    // actually reachable and callers can trade sharpness for memory.
+                    scale: options.pdfOptions?.scale,
+                    maxPages: options.pdfOptions?.maxPages,
                 });
                 logger.info(`[PDF] ✅ Queued for multimodal: ${filename} (${result.metadata?.estimatedPages ?? "unknown"} pages)`);
             }
@@ -1059,41 +1164,10 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
             throw error;
         }
     }
-    // #309: enforce the provider's page/size ceilings across ALL PDFs, not just
-    // per-file. N files each just under the single-file limit can still blow past
-    // it in aggregate (e.g. three 40-page PDFs → 120 pages for a 100-page API).
-    const aggregateConfig = PDFProcessor.getProviderConfig(provider);
-    if (aggregateConfig && pdfFiles.length > 1) {
-        // A null pageCount (accurate count unavailable — see
-        // PDFProcessor.getAccuratePageCount) is treated as 0 in the sum below,
-        // which can undercount the aggregate and let a combined request over
-        // the provider's page limit slip through silently. Enforcement still
-        // runs against the known sum — a PDF with an unknown count must not
-        // fail the request outright — but the gap itself must not be silent.
-        const unknownPageCountFiles = pdfFiles.filter((f) => f.pageCount === null || f.pageCount === undefined);
-        const totalPages = pdfFiles.reduce((sum, f) => sum + (f.pageCount ?? 0), 0);
-        const totalMB = pdfFiles.reduce((sum, f) => sum + f.buffer.length, 0) / (1024 * 1024);
-        if (unknownPageCountFiles.length > 0) {
-            // Filenames are caller-controlled and may be full paths carrying
-            // PII/internal directory segments — log only the basename.
-            const unknownFileNames = unknownPageCountFiles
-                .map((f) => (f.filename ? basename(f.filename) : "<unnamed file>"))
-                .join(", ");
-            logger.warn(`[PDF] Aggregate page-limit check across ${pdfFiles.length} PDFs could only be ` +
-                `partially verified: ${unknownPageCountFiles.length} file(s) have an unknown ` +
-                `page count (${unknownFileNames}), so the known total (${totalPages}) may ` +
-                `undercount the true combined page count.`);
-        }
-        if (totalPages > aggregateConfig.maxPages) {
-            throw new Error(`[PDF] Combined page count across ${pdfFiles.length} PDFs (${totalPages}) exceeds the ` +
-                `${aggregateConfig.maxPages}-page limit for ${provider}. ` +
-                `Split the request or reduce the number of PDFs.`);
-        }
-        if (totalMB > aggregateConfig.maxSizeMB) {
-            throw new Error(`[PDF] Combined size across ${pdfFiles.length} PDFs (${totalMB.toFixed(2)}MB) exceeds the ` +
-                `${aggregateConfig.maxSizeMB}MB limit for ${provider}.`);
-        }
-    }
+    // Counts here come from FileDetector's detection, so they are authoritative.
+    await enforceAggregatePdfLimits(pdfFiles, provider, {
+        trustSuppliedPageCounts: true,
+    });
     return pdfFiles;
 }
 /**
@@ -1389,7 +1463,15 @@ async function convertContentToProviderFormat(content, provider, _model, pdfOpti
         // guard as the `input.pdfFiles` path (see `processExplicitPdfFiles`).
         password: pdfOptions?.password,
         maxCanvasPixels: pdfOptions?.maxCanvasPixels,
+        scale: pdfOptions?.scale,
+        maxPages: pdfOptions?.maxPages,
     }));
+    // #309: same aggregate ceiling as `input.pdfFiles`. Without this, moving an
+    // over-limit payload from `input.pdfFiles` to `input.content` skipped the
+    // check entirely and the request went straight to the provider.
+    await enforceAggregatePdfLimits(pdfFiles, provider, {
+        trustSuppliedPageCounts: false,
+    });
     return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, _model);
 }
 /**
@@ -1734,7 +1816,10 @@ async function convertSimpleImagesToProviderFormat(text, images, provider, _mode
 /**
  * Convert multimodal content (images + PDFs) to provider format
  */
-async function convertMultimodalToProviderFormat(text, images, pdfFiles, provider, model) {
+async function convertMultimodalToProviderFormat(text, images, 
+// The canonical entry shape (#309) rather than a fourth copy of it inline —
+// which is what let the render knobs stop short of this function.
+pdfFiles, provider, model) {
     const content = [
         { type: "text", text },
     ];
@@ -1768,14 +1853,41 @@ async function convertMultimodalToProviderFormat(text, images, pdfFiles, provide
         logger.info(`[PDF→Image] Provider ${provider} doesn't support native PDF. Converting ${pdfFiles.length} PDF(s) to images...`);
         for (const pdf of pdfFiles) {
             try {
+                const effectiveMaxPages = pdf.maxPages ?? PDF_LIMITS.DEFAULT_MAX_PAGES;
                 const conversionResult = await PDFImageConverter.convertToImages(pdf.buffer, {
-                    scale: 2.0, // High quality for OCR/analysis
-                    maxPages: 20, // Limit pages to prevent token overflow
+                    // #297: this is the only PDF→image call the product actually makes,
+                    // and it used to hardcode scale 2.0 — silently overriding the
+                    // lowered PDF_LIMITS.DEFAULT_SCALE and keeping the memory cost the
+                    // issue reports (a 100-page render at 2.0 is ~776MB; 1.5 is ~44%
+                    // fewer pixels per page). Callers can raise it back per request.
+                    scale: pdf.scale ?? PDF_LIMITS.DEFAULT_SCALE,
+                    // Page ceiling guards token overflow; also now caller-adjustable
+                    // rather than a constant nothing could reach.
+                    maxPages: effectiveMaxPages,
                     ...(pdf.password ? { password: pdf.password } : {}), // #258
                     ...(pdf.maxCanvasPixels
                         ? { maxCanvasPixels: pdf.maxCanvasPixels }
                         : {}), // #260
                 });
+                // The renderer stops at maxPages, so a longer document is silently
+                // truncated — say so rather than letting the model answer from a
+                // partial document as though it had the whole thing.
+                //
+                // Keyed on the cap being reached, not on pdf.pageCount: that field is
+                // null whenever `input.content` omits `metadata.pages`, which is the
+                // common case, so a page-count comparison would simply never fire
+                // there. Reaching the cap is also unambiguous — a short count caused by
+                // per-page render failures (#294 isolates those into `errors`) would
+                // otherwise be misreported as a maxPages truncation.
+                if (conversionResult.pageCount >= effectiveMaxPages) {
+                    logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)} hit the ${effectiveMaxPages}-page ` +
+                        `conversion limit. Any pages beyond that were not sent — the model may be ` +
+                        `answering from a partial document. Raise pdfOptions.maxPages or split the file.`);
+                }
+                if (conversionResult.errors && conversionResult.errors.length > 0) {
+                    logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)}: ${conversionResult.errors.length} page(s) ` +
+                        `failed to render and were omitted (page ${conversionResult.errors.map((e) => e.page).join(", ")}).`);
+                }
                 logger.info(`[PDF→Image] ✅ Converted ${pdf.filename}: ${conversionResult.pageCount} page(s) → images`);
                 // Add each page as an ImagePart (raw base64, not data: URI — see SSRF note above)
                 conversionResult.images.forEach((base64Image, pageIndex) => {

package/dist/utils/multimodalOptionsBuilder.d.ts

@@ -58,6 +58,8 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
     pdfOptions: {
         password?: string;
         maxCanvasPixels?: number;
+        scale?: number;
+        maxPages?: number;
     } | undefined;
     systemPrompt: string | undefined;
     conversationHistory: import("../index.js").ChatMessage[] | undefined;

package/dist/utils/pdfProcessor.d.ts

@@ -18,6 +18,17 @@ export declare class PDFProcessor {
      */
     static supportsNativePDF(provider: string): boolean;
     static getProviderConfig(provider: string): PDFProviderConfig | null;
+    /**
+     * Best-effort page count for a PDF whose count the caller did not supply
+     * (#309). Mirrors what `process()` derives for the `input.pdfFiles` path:
+     * the accurate pdfjs count when the document parses, otherwise the header
+     * regex estimate. Returns null when neither can determine a count.
+     *
+     * Exists so the aggregate page-limit guard can enforce against PDFs handed
+     * in via `input.content`, where `metadata.pages` is optional and routinely
+     * omitted — without it, an absent count silently sums as zero.
+     */
+    static resolvePageCount(buffer: Buffer): Promise<number | null>;
     private static isValidPDF;
     private static extractBasicMetadata;
     /**

package/dist/utils/pdfProcessor.js

@@ -212,6 +212,23 @@ export class PDFProcessor {
     static getProviderConfig(provider) {
         return PDF_PROVIDER_CONFIGS[provider] || null;
     }
+    /**
+     * Best-effort page count for a PDF whose count the caller did not supply
+     * (#309). Mirrors what `process()` derives for the `input.pdfFiles` path:
+     * the accurate pdfjs count when the document parses, otherwise the header
+     * regex estimate. Returns null when neither can determine a count.
+     *
+     * Exists so the aggregate page-limit guard can enforce against PDFs handed
+     * in via `input.content`, where `metadata.pages` is optional and routinely
+     * omitted — without it, an absent count silently sums as zero.
+     */
+    static async resolvePageCount(buffer) {
+        const accurate = await PDFProcessor.getAccuratePageCount(buffer);
+        if (accurate !== null) {
+            return accurate;
+        }
+        return PDFProcessor.extractBasicMetadata(buffer).estimatedPages;
+    }
     static isValidPDF(buffer) {
         if (buffer.length < 5) {
             return false;
@@ -360,6 +377,7 @@ export class PDFProcessor {
             format,
             scale,
             maxCanvasPixels,
+            maxPages,
         });
         logger.debug("[PDF→Image] ✅ PDF validation passed", {
             bufferSize: pdfBuffer.length,
@@ -518,6 +536,14 @@ export class PDFProcessor {
         if (!Number.isFinite(opts.maxCanvasPixels) || opts.maxCanvasPixels <= 0) {
             throw new Error(`Invalid maxCanvasPixels: ${opts.maxCanvasPixels}. Must be a finite number greater than 0.`);
         }
+        // #297: maxPages became caller-controlled, and an unvalidated 0/-1/NaN
+        // silently converts nothing, surfacing later as a misleading
+        // "PDF has 0 pages" from deep inside the renderer. Reject it here where
+        // the message can still name the offending option.
+        if (opts.maxPages !== undefined &&
+            (!Number.isInteger(opts.maxPages) || opts.maxPages < 1)) {
+            throw new Error(`Invalid maxPages: ${opts.maxPages}. Must be a whole number of at least 1.`);
+        }
         if (!pdfBuffer || pdfBuffer.length < 5) {
             throw new Error("Invalid PDF: Buffer is too small or empty. " +
                 "A valid PDF must be at least 5 bytes (PDF header).");
@@ -553,6 +579,7 @@ export class PDFProcessor {
             format,
             scale,
             maxCanvasPixels,
+            maxPages,
         });
         const pdfToImgModule = await import("pdf-to-img");
         const pdf = pdfToImgModule.pdf;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "10.10.7",
+  "version": "10.10.9",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {