@juspay/neurolink 10.10.8 → 10.10.10

package/dist/skills/skillsManager.js

@@ -87,7 +87,14 @@ export class SkillsManager {
         // name-find would resolve non-deterministically to the stale deprecated one
         // across store backends. Fall back to any match only when no active skill
         // carries the name.
-        const entry = index.find((item) => item.name === idOrName && (item.status ?? "active") === "active") ?? index.find((item) => item.name === idOrName);
+        //
+        // Matched case-insensitively to agree with assertNameAvailable, which
+        // enforces uniqueness that way: names differing only in case cannot
+        // coexist, so a case-sensitive lookup could only fail to find a skill that
+        // is definitively there (`get("DEPLOY")` returned null for "deploy").
+        const wanted = idOrName.toLowerCase();
+        const entry = index.find((item) => item.name.toLowerCase() === wanted &&
+            (item.status ?? "active") === "active") ?? index.find((item) => item.name.toLowerCase() === wanted);
         return entry ? this.store.get(entry.id) : null;
     }
     /**
@@ -237,11 +244,23 @@ export class SkillsManager {
     }
     async assertNameAvailable(name, excludeId) {
         const index = await this.getIndex(true);
-        const clash = index.find((item) => item.id !== excludeId &&
-            item.name.toLowerCase() === name.toLowerCase() &&
-            (item.status ?? "active") === "active");
+        // Deliberately NOT filtered to active (#1139). Soft-delete only flips
+        // status to "deprecated" — the entry stays in the index, so allowing a new
+        // skill to take the name left two entries sharing it. Every name-based
+        // lookup (CLI `skills show/delete <name>`, the skill_update/skill_delete
+        // tools, the `:id`-or-name REST routes) then had to guess which one the
+        // caller meant, and iteration order differs across store backends.
+        //
+        // A deprecated skill's name therefore stays reserved. Reusing it requires
+        // hard-deleting the old skill first, which is the explicit choice the
+        // ambiguity demands.
+        const clash = index.find((item) => item.id !== excludeId && item.name.toLowerCase() === name.toLowerCase());
         if (clash) {
-            throw new Error(`A skill named "${name}" already exists`);
+            const suffix = (clash.status ?? "active") === "active"
+                ? ""
+                : ` (that name belongs to a deprecated skill, id ${clash.id}; ` +
+                    `remove it before reusing the name)`;
+            throw new Error(`A skill named "${name}" already exists${suffix}`);
         }
     }
 }

package/dist/types/file.d.ts

@@ -200,6 +200,12 @@ export type CSVProcessorOptions = {
      * rather than hanging forever. Defaults: 30s for strings, 5min for files.
      */
     parseTimeoutMs?: number;
+    /**
+     * Skip blank / whitespace-only data rows (#373). Default `true`: blank lines
+     * are excluded from the returned content (including raw CSV text) and from
+     * `metadata.rowCount`. Set to `false` to preserve empty lines literally.
+     */
+    skipEmptyLines?: boolean;
 };
 /**
  * PDF API types for different providers
@@ -474,6 +480,10 @@ export type MultimodalPdfEntry = {
     password?: string;
     /** Per-page pixel ceiling for the image fallback (#260). */
     maxCanvasPixels?: number;
+    /** Render scale for the image fallback (#297). */
+    scale?: number;
+    /** Max pages converted by the image fallback (#297). */
+    maxPages?: number;
 };
 /** Result of PDF to image conversion. */
 export type PDFImageConversionResult = {

package/dist/types/generate.d.ts

@@ -133,6 +133,17 @@ export type GenerateOptions = {
         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. */
@@ -1265,6 +1276,10 @@ export type TextGenerationOptions = {
         password?: string;
         /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
         maxCanvasPixels?: number;
+        /** Render scale for the image fallback (#297); defaults to PDF_LIMITS.DEFAULT_SCALE. */
+        scale?: number;
+        /** Max pages converted by the image fallback (#297); defaults to PDF_LIMITS.DEFAULT_MAX_PAGES. */
+        maxPages?: number;
     };
     enableSummarization?: boolean;
     /**

package/dist/types/processor.d.ts

@@ -703,6 +703,12 @@ export type ProcessedAudio = ProcessedFileBase & {
     transcript?: string;
     hasTranscript: boolean;
     transcriptionProvider?: string;
+    /**
+     * Why transcription produced nothing, when it did (#416). Absent on success.
+     * Lets a caller distinguish "this audio has no speech" from "the transcription
+     * backend was never reachable", which previously looked identical.
+     */
+    transcriptionSkippedReason?: string;
     coverArt?: Buffer;
 };
 /**

package/dist/types/stream.d.ts

@@ -225,6 +225,17 @@ 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. */

package/dist/utils/csvProcessor.d.ts

@@ -30,6 +30,18 @@ export declare function isValidCsvRow(row: unknown): row is CSVRow;
  * match) when a row violates the invariant.
  */
 export declare function assertValidCsvRow(row: unknown, rowNumber: number): asserts row is CSVRow;
+/**
+ * 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 declare function isBlankCsvDataRow(row: CSVRow): boolean;
+/**
+ * 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 declare function isBlankCsvRawLine(line: string, delimiter: string): boolean;
 /**
  * Detect if first line is CSV metadata (not actual data/headers)
  * Common patterns:
@@ -174,11 +186,17 @@ export declare 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.
      */
     private static formatForLLM;
     /**
      * 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.
      */
     private static toMarkdownTable;
     /**
@@ -187,6 +205,7 @@ export declare 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
      */
     private static formatSampleData;
@@ -195,6 +214,7 @@ export declare 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
      */
     private static toCSVString;

package/dist/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(",") ||