@juspay/neurolink 10.10.8 → 10.10.10

package/dist/lib/utils/csvProcessor.js

@@ -180,6 +180,37 @@ export function assertValidCsvRow(row, rowNumber) {
         throw ErrorFactory.csvRowInvalid(`[CSVProcessor] Invalid CSV row ${rowNumber}: expected a string-keyed object with string values, got ${Array.isArray(row) ? "array" : typeof row}`, rowNumber);
     }
 }
+/**
+ * True when a parsed CSV row is blank: no keys, or every value is empty /
+ * whitespace-only (#373). Shared by the structured post-filter and by
+ * `streamParse` so blank rows do not consume `maxRows`.
+ */
+export function isBlankCsvDataRow(row) {
+    const keys = Object.keys(row);
+    if (keys.length === 0) {
+        return true;
+    }
+    return Object.values(row).every((val) => val === "" || (typeof val === "string" && val.trim() === ""));
+}
+/**
+ * Raw-line counterpart of {@link isBlankCsvDataRow} (#373): a fully blank /
+ * whitespace line, or a delimiter-only line such as `,,` / `  ,  ` whose
+ * fields are all empty after a CSV-aware split.
+ */
+export function isBlankCsvRawLine(line, delimiter) {
+    if (line.trim() === "") {
+        return true;
+    }
+    const fields = splitCSVFields(line, delimiter);
+    if (fields.length === 0) {
+        return true;
+    }
+    const row = Object.create(null);
+    for (let i = 0; i < fields.length; i++) {
+        row[`c${i}`] = fields[i];
+    }
+    return isBlankCsvDataRow(row);
+}
 // ============================================================================
 // Parse Error Context (#375)
 // ============================================================================
@@ -624,18 +655,41 @@ function isMetadataLine(lines) {
     }
     const firstLine = lines[0].trim();
     const secondLine = lines[1].trim();
+    // Excel's explicit-delimiter preamble is metadata regardless of what follows.
     if (firstLine.match(/^sep=/i)) {
         return true;
     }
+    // #373: this check has to come BEFORE the comma-count heuristics, not after.
+    // Both of them read a higher comma count on line 2 as "line 1 was a preamble"
+    // — but a delimiter-only row (`,,`) is a blank DATA row, and its commas are
+    // structure, not fields. Ordered the other way, a legitimate single-column
+    // header followed by a blank row (`name` / `,,`) tripped the zero-vs-nonzero
+    // rule and stripMetadataLine() deleted the real header, leaving unnamed
+    // columns. Verified against `name\n,,\nalice\nbob`.
+    if (isDelimiterOnlyOrBlankLine(secondLine)) {
+        return false;
+    }
     const firstCommaCount = countUnquotedCommas(firstLine);
     const secondCommaCount = countUnquotedCommas(secondLine);
+    // A title/preamble line carries no delimiters while the header below it does.
     if (firstCommaCount === 0 && secondCommaCount > 0) {
         return true;
     }
-    if (secondCommaCount > 0 && firstCommaCount !== secondCommaCount) {
+    // Differing field counts mean line 1 is not part of the same table as line 2.
+    return secondCommaCount > 0 && firstCommaCount !== secondCommaCount;
+}
+/**
+ * True when `line` is empty/whitespace or contains only common CSV
+ * delimiters (comma / tab / semicolon / pipe) and whitespace — i.e. a
+ * delimiter-only blank row like `,,` or `  ;  ;  `. Used before the
+ * delimiter is known (metadata detection).
+ */
+function isDelimiterOnlyOrBlankLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === "") {
         return true;
     }
-    return false;
+    return /^[\s,;\t|]+$/.test(trimmed) && /[,;\t|]/.test(trimmed);
 }
 /**
  * Strip a leading metadata line (e.g. Excel's `sep=;` preamble) from
@@ -737,13 +791,14 @@ export class CSVProcessor {
      * @returns Formatted CSV data ready for LLM (JSON or Markdown)
      */
     static async process(content, options) {
-        const { maxRows: rawMaxRows = 1000, formatStyle = "raw", includeHeaders = true, sampleDataFormat = "json", extension = null, encoding, sanitizeColumnNames = false, columnNameCase = "snake_case", parseTimeoutMs = DEFAULT_CSV_STRING_PARSE_TIMEOUT_MS, } = options || {};
+        const { maxRows: rawMaxRows = 1000, formatStyle = "raw", includeHeaders = true, sampleDataFormat = "json", extension = null, encoding, sanitizeColumnNames = false, columnNameCase = "snake_case", parseTimeoutMs = DEFAULT_CSV_STRING_PARSE_TIMEOUT_MS, skipEmptyLines = true, } = options || {};
         const maxRows = Math.max(1, Math.min(10000, rawMaxRows));
         logger.debug("[CSVProcessor] Starting CSV processing", {
             contentSize: content.length,
             formatStyle,
             maxRows,
             includeHeaders,
+            skipEmptyLines,
         });
         // #362: detect the encoding (BOM → chardet → UTF-8 fallback) or honor the
         // caller's override, instead of the previous hard-coded UTF-8 decode.
@@ -764,7 +819,15 @@ export class CSVProcessor {
             }
             // dataLines already has the metadata line (if any) stripped.
             const csvLines = dataLines;
-            const limitedLines = csvLines.slice(0, 1 + maxRows); // header + data rows
+            const headerLine = csvLines[0] ?? "";
+            const rawDataLines = csvLines.slice(1);
+            // #373: drop blank AND delimiter-only data lines (e.g. `,,`) so raw
+            // content matches structured `isBlankCsvDataRow` semantics.
+            const effectiveDataLines = skipEmptyLines
+                ? rawDataLines.filter((line) => !isBlankCsvRawLine(line, delimiter))
+                : rawDataLines;
+            const limitedDataLines = effectiveDataLines.slice(0, maxRows);
+            const limitedLines = csvLines.length === 0 ? [] : [headerLine, ...limitedDataLines];
             // #378: opt-in — rewrite the literal header line with sanitized,
             // deduped identifiers so the raw CSV text shown to the LLM has clean
             // column names too. (Splits on commas to match the existing raw-branch
@@ -780,12 +843,10 @@ export class CSVProcessor {
             // #1199: quote-aware, delimiter-aware split (matches the
             // sanitizeColumnNames branch above and #1192's detected delimiter).
             const headerFields = splitCSVFields(limitedLines[0] || "", delimiter);
-            const rowCount = limitedLines
-                .slice(1)
-                .filter((line) => line.trim() !== "").length;
-            const originalRowCount = csvLines
-                .slice(1)
-                .filter((line) => line.trim() !== "").length;
+            // When preserving empties, blank lines count as rows; when skipping,
+            // only non-empty data lines do.
+            const rowCount = limitedDataLines.length;
+            const originalRowCount = effectiveDataLines.length;
             const wasTruncated = rowCount < originalRowCount;
             if (wasTruncated) {
                 logger.warn(`[CSVProcessor] CSV data truncated: showing ${rowCount} of ${originalRowCount} rows (limit: ${maxRows})`);
@@ -802,17 +863,16 @@ export class CSVProcessor {
                 truncated: wasTruncated,
             });
             // Parse a sample for enhanced metadata analysis (raw format still
-            // benefits from column analysis). Reuse the already-split, already
-            // metadata-stripped `dataLines` and the already-detected `delimiter`
-            // via the shared streamParse() core instead of routing `limitedCSV`
-            // back through parseCSVStringWithMeta(), which would re-split/re-join
-            // it and re-run a redundant BOM/metadata/delimiter-detection pass.
+            // benefits from column analysis). Feed the already-filtered limited
+            // lines and honor skipEmptyRows so blank/delimiter-only rows do not
+            // consume the sample limit (#373).
             const sampleRows = Math.min(rowCount, 500);
-            const { rows: sampleForAnalysis, timedOut: rawTimedOut } = await this.streamParse(Readable.from([dataLines.slice(0, 1 + sampleRows).join("\n")]), undefined, {
+            const { rows: sampleForAnalysis, timedOut: rawTimedOut } = await this.streamParse(Readable.from([limitedLines.join("\n")]), undefined, {
                 maxRows: sampleRows,
                 skipLines: 0,
                 timeoutMs: parseTimeoutMs,
                 delimiter,
+                skipEmptyRows: skipEmptyLines,
             });
             const { columnMetadata, dataQualityWarnings, dataQualityScore } = analyzeColumns(sampleForAnalysis);
             // Log data quality summary
@@ -856,51 +916,83 @@ export class CSVProcessor {
         // `delimiter`) — reuse both via the shared streamParse() core instead of
         // routing csvString back through parseCSVStringWithMeta(), which would
         // re-split it and re-run metadata/delimiter detection a second time.
-        const { rows, timedOut: structuredTimedOut } = await this.streamParse(Readable.from([dataLines.join("\n")]), undefined, { maxRows, skipLines: 0, timeoutMs: parseTimeoutMs, delimiter });
-        // Filter out empty rows (empty objects or rows with only whitespace values from blank lines)
+        const { rows, timedOut: structuredTimedOut, headers: parsedHeaders, } = await this.streamParse(Readable.from([dataLines.join("\n")]), undefined, {
+            maxRows,
+            skipLines: 0,
+            timeoutMs: parseTimeoutMs,
+            delimiter,
+            // Count only non-blank rows toward maxRows when skipping empties
+            // (#373), so maxRows: 2 still yields two real data rows if blanks
+            // appear first.
+            skipEmptyRows: skipEmptyLines,
+        });
+        // Filter out empty rows (empty objects or rows with only whitespace values
+        // from blank lines). #373: `skipEmptyLines` (default true) controls this;
+        // set false to preserve blank-line rows in structured output.
         const filteredRows = rows.filter((row) => {
             if (!row || typeof row !== "object") {
                 return false;
             }
-            const keys = Object.keys(row);
-            if (keys.length === 0) {
-                return false;
+            if (!skipEmptyLines) {
+                return true;
             }
-            // Check if all values are empty or whitespace-only
-            return !Object.values(row).every((val) => val === "" || (typeof val === "string" && val.trim() === ""));
+            return !isBlankCsvDataRow(row);
         });
+        // Schema must come from parser headers or the first non-blank data row,
+        // never from a preserved leading blank row (#373 review).
+        const schemaRow = filteredRows.find((row) => row && typeof row === "object" && !isBlankCsvDataRow(row));
+        const schemaHeaders = (parsedHeaders && parsedHeaders.length > 0
+            ? [...parsedHeaders]
+            : undefined) ??
+            (schemaRow ? Object.keys(schemaRow) : undefined) ??
+            (filteredRows[0] ? Object.keys(filteredRows[0]) : []) ??
+            [];
         // #378: opt-in — remap each row's keys from original → sanitized identifiers.
+        // Always project onto schemaHeaders first so preserved blank rows still
+        // carry the real column keys for Markdown/JSON (#373 review).
         let structuredColumnNameMapping;
         const sanitizedToOriginal = new Map();
-        let nonEmptyRows = filteredRows;
-        if (sanitizeColumnNames && filteredRows.length > 0) {
-            const origHeaders = Object.keys(filteredRows[0]);
+        let columnNames = schemaHeaders;
+        let nonEmptyRows = schemaHeaders.length === 0
+            ? filteredRows
+            : filteredRows.map((row) => {
+                const out = Object.create(null);
+                for (const h of schemaHeaders) {
+                    out[h] = typeof row[h] === "string" ? row[h] : "";
+                }
+                return out;
+            });
+        if (sanitizeColumnNames && schemaHeaders.length > 0) {
+            const origHeaders = schemaHeaders;
             const { sanitized, mapping } = buildColumnNameMapping(origHeaders, columnNameCase);
             origHeaders.forEach((original, i) => {
                 if (original !== sanitized[i]) {
                     sanitizedToOriginal.set(sanitized[i], original);
                 }
             });
-            nonEmptyRows = filteredRows.map((row) => {
+            nonEmptyRows = nonEmptyRows.map((row) => {
                 // Defense-in-depth: a null-prototype target means an attacker-chosen
                 // header literally named "__proto__"/"constructor"/"prototype" can
                 // only ever create a harmless own property, never touch
                 // Object.prototype (#1199).
                 const out = Object.create(null);
                 origHeaders.forEach((h, i) => {
-                    out[sanitized[i]] = row[h];
+                    out[sanitized[i]] = row[h] ?? "";
                 });
                 return out;
             });
             structuredColumnNameMapping = mapping.length > 0 ? mapping : undefined;
+            columnNames = sanitized;
         }
         // Extract metadata from parsed results
         const rowCount = nonEmptyRows.length;
-        const columnNames = nonEmptyRows.length > 0 ? Object.keys(nonEmptyRows[0]) : [];
         const columnCount = columnNames.length;
         const hasEmptyColumns = columnNames.some((col) => !col || col.trim() === "");
-        const sampleRows = nonEmptyRows.slice(0, 3);
-        const sampleData = this.formatSampleData(sampleRows, sampleDataFormat, includeHeaders);
+        // Sample / analysis should prefer non-blank rows so a preserved leading
+        // blank does not poison type detection or formatSampleData.
+        const rowsForAnalysis = nonEmptyRows.filter((row) => !isBlankCsvDataRow(row));
+        const sampleRows = (rowsForAnalysis.length > 0 ? rowsForAnalysis : nonEmptyRows).slice(0, 3);
+        const sampleData = this.formatSampleData(sampleRows, sampleDataFormat, includeHeaders, columnNames);
         if (hasEmptyColumns) {
             logger.warn("[CSVProcessor] CSV contains empty or blank column headers", {
                 columnNames,
@@ -909,8 +1001,9 @@ export class CSVProcessor {
         if (rowCount === 0) {
             logger.warn("[CSVProcessor] CSV file contains no data rows");
         }
-        // Perform enhanced column analysis
-        const { columnMetadata, dataQualityWarnings, dataQualityScore } = analyzeColumns(nonEmptyRows);
+        // Perform enhanced column analysis on non-blank rows so preserved
+        // leading blanks do not yield an empty schema (#373 review).
+        const { columnMetadata, dataQualityWarnings, dataQualityScore } = analyzeColumns(rowsForAnalysis.length > 0 ? rowsForAnalysis : nonEmptyRows);
         // #378: carry the pre-sanitization header on each renamed column.
         if (sanitizedToOriginal.size > 0) {
             for (const col of columnMetadata) {
@@ -929,7 +1022,7 @@ export class CSVProcessor {
         }
         // Format parsed data
         logger.debug(`[CSVProcessor] Converting ${rowCount} rows to ${formatStyle} format`);
-        const formatted = this.formatForLLM(nonEmptyRows, formatStyle, includeHeaders);
+        const formatted = this.formatForLLM(nonEmptyRows, formatStyle, includeHeaders, columnNames);
         logger.info("[CSVProcessor] ✅ Processed CSV file", {
             formatStyle,
             rowCount,
@@ -954,7 +1047,7 @@ export class CSVProcessor {
                 columnMetadata,
                 dataQualityWarnings,
                 dataQualityScore,
-                hasHeaders: detectHasHeaders(columnNames, nonEmptyRows),
+                hasHeaders: detectHasHeaders(columnNames, rowsForAnalysis.length > 0 ? rowsForAnalysis : nonEmptyRows),
                 detectedDelimiter: delimiter,
                 detectedEncoding,
                 encodingConfidence,
@@ -1240,7 +1333,7 @@ export class CSVProcessor {
                 finish(() => {
                     logger.warn(`[CSVProcessor] Parse timed out after ${Date.now() - startTime}ms with ${rows.length} partial row(s)`);
                     abort();
-                    resolve({ rows, timedOut: true });
+                    resolve({ rows, timedOut: true, headers: capturedHeaders });
                 });
             }, opts.timeoutMs);
             if (typeof timer.unref === "function") {
@@ -1277,6 +1370,10 @@ export class CSVProcessor {
                     });
                     return;
                 }
+                // #373: blank rows must not consume maxRows when skipping empties.
+                if (opts.skipEmptyRows && isBlankCsvDataRow(row)) {
+                    return;
+                }
                 lastRowColumnCount = Object.keys(row).length;
                 rows.push(row);
                 count++;
@@ -1284,14 +1381,14 @@ export class CSVProcessor {
                     logger.debug(`[CSVProcessor] Reached row limit ${opts.maxRows}, stopping parse`);
                     finish(() => {
                         abort();
-                        resolve({ rows, timedOut: false });
+                        resolve({ rows, timedOut: false, headers: capturedHeaders });
                     });
                 }
             })
                 .on("end", () => {
                 finish(() => {
                     logger.debug(`[CSVProcessor] Parsing complete: ${rows.length} rows parsed`);
-                    resolve({ rows, timedOut: false });
+                    resolve({ rows, timedOut: false, headers: capturedHeaders });
                 });
             })
                 .on("error", (error) => {
@@ -1315,25 +1412,36 @@ export class CSVProcessor {
     /**
      * Format parsed CSV data for LLM consumption
      * Only used for JSON and Markdown formats (raw format handled separately)
+     *
+     * @param columnNames - Optional schema headers (#373). When preserved blank
+     *   rows lead `rows`, Markdown must still use the real column names.
      */
-    static formatForLLM(rows, formatStyle, includeHeaders) {
+    static formatForLLM(rows, formatStyle, includeHeaders, columnNames) {
         if (rows.length === 0) {
             return "CSV file is empty or contains no data.";
         }
         if (formatStyle === "json") {
             return JSON.stringify(rows, null, 2);
         }
-        return this.toMarkdownTable(rows, includeHeaders);
+        return this.toMarkdownTable(rows, includeHeaders, columnNames);
     }
     /**
      * Format as markdown table
      * Best for small datasets (<100 rows)
+     *
+     * @param columnNames - Optional explicit headers (#373). Falls back to
+     *   `Object.keys(rows[0])` when omitted.
      */
-    static toMarkdownTable(rows, includeHeaders) {
+    static toMarkdownTable(rows, includeHeaders, columnNames) {
         if (rows.length === 0) {
             return "CSV file is empty or contains no data.";
         }
-        const headers = Object.keys(rows[0]);
+        const headers = columnNames && columnNames.length > 0
+            ? columnNames
+            : Object.keys(rows[0] ?? {});
+        if (headers.length === 0) {
+            return "CSV file is empty or contains no data.";
+        }
         // Escape backslashes, pipes, and sanitize newlines to keep rows intact
         const escapePipe = (str) => str
             .replace(/\\/g, "\\\\")
@@ -1358,9 +1466,10 @@ export class CSVProcessor {
      * @param sampleRows - Array of sample row objects
      * @param format - Output format for sample data
      * @param includeHeaders - Whether to include headers in CSV/markdown formats
+     * @param columnNames - Optional schema headers for csv/markdown (#373)
      * @returns Formatted sample data as string or array
      */
-    static formatSampleData(sampleRows, format, includeHeaders) {
+    static formatSampleData(sampleRows, format, includeHeaders, columnNames) {
         if (sampleRows.length === 0) {
             return format === "object" ? [] : "No data rows";
         }
@@ -1370,9 +1479,9 @@ export class CSVProcessor {
             case "json":
                 return JSON.stringify(sampleRows, null, 2);
             case "csv":
-                return this.toCSVString(sampleRows, includeHeaders);
+                return this.toCSVString(sampleRows, includeHeaders, columnNames);
             case "markdown":
-                return this.toMarkdownTable(sampleRows, includeHeaders);
+                return this.toMarkdownTable(sampleRows, includeHeaders, columnNames);
             default:
                 return sampleRows;
         }
@@ -1382,13 +1491,19 @@ export class CSVProcessor {
      *
      * @param rows - Array of row objects
      * @param includeHeaders - Whether to include header row
+     * @param columnNames - Optional explicit headers (#373)
      * @returns CSV formatted string
      */
-    static toCSVString(rows, includeHeaders) {
+    static toCSVString(rows, includeHeaders, columnNames) {
         if (rows.length === 0) {
             return "";
         }
-        const headers = Object.keys(rows[0]);
+        const headers = columnNames && columnNames.length > 0
+            ? columnNames
+            : Object.keys(rows[0] ?? {});
+        if (headers.length === 0) {
+            return "";
+        }
         // Escape CSV values (wrap in quotes if contains comma, quote, or newline)
         const escapeCSV = (value) => {
             if (value.includes(",") ||

package/dist/lib/utils/messageBuilder.js

@@ -4,6 +4,7 @@ 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";
@@ -1150,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)`);
             }
@@ -1458,6 +1463,8 @@ 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
@@ -1809,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 },
     ];
@@ -1843,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/lib/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("../types/conversation.js").ChatMessage[] | undefined;

package/dist/lib/utils/pdfProcessor.js

@@ -377,6 +377,7 @@ export class PDFProcessor {
             format,
             scale,
             maxCanvasPixels,
+            maxPages,
         });
         logger.debug("[PDF→Image] ✅ PDF validation passed", {
             bufferSize: pdfBuffer.length,
@@ -535,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).");
@@ -570,6 +579,7 @@ export class PDFProcessor {
             format,
             scale,
             maxCanvasPixels,
+            maxPages,
         });
         const pdfToImgModule = await import("pdf-to-img");
         const pdf = pdfToImgModule.pdf;

package/dist/processors/media/AudioProcessor.js

@@ -41,6 +41,7 @@ import { SIZE_LIMITS_MB } from "../config/index.js";
 import { FileErrorCode } from "../errors/index.js";
 import { withTimeout } from "../../utils/timeout.js";
 import { formatMediaDuration } from "../../utils/mediaDuration.js";
+import { logger } from "../../utils/logger.js";
 import { tryImport } from "../../utils/tryImport.js";
 let _musicMetadata = null;
 async function loadMusicMetadata() {
@@ -264,6 +265,11 @@ export class AudioProcessor extends BaseFileProcessor {
                     transcript: transcriptionResult.transcript,
                     hasTranscript: transcriptionResult.hasTranscript,
                     transcriptionProvider: transcriptionResult.transcriptionProvider,
+                    ...(transcriptionResult.transcriptionSkippedReason
+                        ? {
+                            transcriptionSkippedReason: transcriptionResult.transcriptionSkippedReason,
+                        }
+                        : {}),
                     coverArt: coverArt ?? undefined,
                     buffer,
                     mimetype: fileInfo.mimetype || "audio/mpeg",
@@ -316,20 +322,25 @@ export class AudioProcessor extends BaseFileProcessor {
      * @returns Transcription result with transcript text, or empty result
      */
     async attemptTranscription(buffer, filename, mimetype) {
-        const emptyResult = {
-            transcript: undefined,
-            hasTranscript: false,
-            transcriptionProvider: undefined,
+        const skipped = (reason) => {
+            logger.warn(`[AudioProcessor] No transcript for ${filename}: ${reason}. ` +
+                `The model will receive metadata only.`);
+            return {
+                transcript: undefined,
+                hasTranscript: false,
+                transcriptionProvider: undefined,
+                transcriptionSkippedReason: reason,
+            };
         };
         // Check if OPENAI_API_KEY is available
         const apiKey = process.env.OPENAI_API_KEY;
         if (!apiKey) {
-            return emptyResult;
+            return skipped("OPENAI_API_KEY is not set, and Whisper is the only transcription backend wired up");
         }
         // Check file size (Whisper limit is 25MB)
         const fileSizeMB = buffer.length / (1024 * 1024);
         if (fileSizeMB > AUDIO_CONFIG.WHISPER_MAX_SIZE_MB) {
-            return emptyResult;
+            return skipped(`file is ${fileSizeMB.toFixed(1)}MB, over Whisper's ${AUDIO_CONFIG.WHISPER_MAX_SIZE_MB}MB limit — split or compress it`);
         }
         // Check if file format is supported by Whisper
         const ext = filename.split(".").pop()?.toLowerCase();
@@ -343,7 +354,7 @@ export class AudioProcessor extends BaseFileProcessor {
                 mimetype.startsWith("audio/ogg") ||
                 mimetype.startsWith("audio/x-m4a"));
         if (!isFormatSupported && !isMimeSupported) {
-            return emptyResult;
+            return skipped(`format is not one Whisper accepts (extension "${ext ?? "none"}", mimetype "${mimetype ?? "none"}"); supported: ${AUDIO_CONFIG.WHISPER_SUPPORTED_FORMATS.join(", ")}`);
         }
         try {
             // Dynamic imports to avoid loading these modules when transcription is not needed
@@ -351,26 +362,33 @@ export class AudioProcessor extends BaseFileProcessor {
             const openai = createOpenAI({ apiKey });
             const model = openai.transcription("whisper-1");
             // Wrap in withTimeout — large audio files can take a while, but a
-            // stalled request shouldn't block the processor forever. The outer
-            // catch swallows any error (transcription is best-effort), so a
-            // TimeoutError ends up in the same fallback path as other failures.
+            // stalled request shouldn't block the processor forever. A TimeoutError
+            // lands in the same handler as other failures below, which reports it as
+            // the reason rather than discarding it.
             const result = await withTimeout(experimental_transcribe({
                 model,
                 audio: buffer,
             }), AUDIO_CONFIG.TRANSCRIPTION_TIMEOUT_MS, "openai-whisper", "generate");
             if (result.text && result.text.trim().length > 0) {
+                logger.debug(`[AudioProcessor] Transcribed ${filename} via openai-whisper (${result.text.trim().length} chars)`);
                 return {
                     transcript: result.text.trim(),
                     hasTranscript: true,
                     transcriptionProvider: "openai-whisper",
+                    transcriptionSkippedReason: undefined,
                 };
             }
-            return emptyResult;
+            // A successful call that returned nothing is a legitimate outcome
+            // (silence, music, no speech) — distinct from a failure.
+            return skipped("Whisper returned an empty transcript for this audio");
         }
-        catch {
-            // Transcription is best-effort — never fail the entire processing pipeline
-            // Common failures: rate limiting, network issues, unsupported audio encoding
-            return emptyResult;
+        catch (error) {
+            // Transcription stays best-effort — a failure must never kill the whole
+            // processing pipeline. But discarding the error outright, as this block
+            // used to, made a bad API key, a rate limit and a network blip all look
+            // identical to "this file has no speech in it".
+            const message = error instanceof Error ? error.message : String(error);
+            return skipped(`transcription request failed — ${message}`);
         }
     }
     // ===========================================================================