@juspay/neurolink 12.30.1 → 12.31.0

package/dist/cli/loop/optionsSchema.d.ts

@@ -4,4 +4,4 @@ import type { OptionSchema, TextGenerationOptions } from "../../types/index.js";
  * This object provides metadata for validation and help text in the CLI loop.
  * It is derived from the main TextGenerationOptions interface to ensure consistency.
  */
-export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "pdfOptions" | "imageOptions" | "videoOptions" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation" | "toolExecutionCapture" | "toolExecutionRecorder" | "toolRoots">, OptionSchema>;
+export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "pdfOptions" | "imageOptions" | "videoOptions" | "officeOptions" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation" | "toolExecutionCapture" | "toolExecutionRecorder" | "toolRoots">, OptionSchema>;

package/dist/core/baseProvider.js

@@ -937,6 +937,7 @@ export class BaseProvider {
                 csvOptions: options.csvOptions,
                 pdfOptions: options.pdfOptions,
                 videoOptions: options.videoOptions,
+                officeOptions: options.officeOptions,
                 // Forward abort, tool filtering, and timeout options to prevent
                 // silent bypass when falling back from real streaming to fake streaming
                 abortSignal: options.abortSignal,

package/dist/core/modules/MessageBuilder.js

@@ -109,6 +109,11 @@ export class MessageBuilder {
                     // transcription flag are read downstream by the detector, and
                     // a reconstruction that omits them silently restores defaults.
                     videoOptions: options.videoOptions,
+                    // This object is rebuilt field by field, so anything not named
+                    // here never reaches the multimodal builder — the same way
+                    // audioFiles/videoFiles went missing in #284. Office options
+                    // steer XLSX sheet selection and rendering.
+                    officeOptions: options.officeOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,
@@ -244,6 +249,11 @@ export class MessageBuilder {
                     // transcription flag are read downstream by the detector, and
                     // a reconstruction that omits them silently restores defaults.
                     videoOptions: options.videoOptions,
+                    // This object is rebuilt field by field, so anything not named
+                    // here never reaches the multimodal builder — the same way
+                    // audioFiles/videoFiles went missing in #284. Office options
+                    // steer XLSX sheet selection and rendering.
+                    officeOptions: options.officeOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,

package/dist/neurolink.js

@@ -4284,6 +4284,7 @@ Current user's request: ${currentInput}`;
             // caller's video settings have ever reached a provider -- frames and
             // quality included, not just the native-video flags added alongside.
             videoOptions: options.videoOptions,
+            officeOptions: options.officeOptions,
             region: options.region,
             tts: options.tts,
             stt: options.stt,

package/dist/processors/document/ExcelProcessor.d.ts

@@ -36,7 +36,7 @@
  * ```
  */
 import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
-import type { FileInfo, ProcessOptions, ProcessedExcel, ProcessorFileProcessingResult } from "../../types/index.js";
+import type { ExcelWorksheet, FileInfo, OfficeProcessorOptions, ProcessOptions, ProcessedExcel, ProcessorFileProcessingResult } from "../../types/index.js";
 /**
  * Excel Processor - handles .xlsx and .xls files.
  * Uses exceljs library for parsing with support for large files.
@@ -136,6 +136,18 @@ export declare class ExcelProcessor extends BaseFileProcessor<ProcessedExcel> {
      */
     extractSheetRange(buffer: Buffer, sheet?: string | number, rowStart?: number, rowEnd?: number, columns?: string[]): Promise<string>;
 }
+/**
+ * Render processed worksheets into the text handed to the model.
+ *
+ * @param worksheets - Worksheets extracted from the workbook
+ * @param totalRows - Total row count across all extracted worksheets
+ * @param options - Office options; `sheetName` selects a single sheet and
+ *   `formatStyle` chooses the rendering (default `raw`, the tab-separated
+ *   preview that predates the option)
+ * @returns Prompt-ready text, or a message naming the available sheets when
+ *   `sheetName` matches none of them
+ */
+export declare function formatWorksheetsForPrompt(worksheets: ExcelWorksheet[], totalRows: number, options?: OfficeProcessorOptions): string;
 /**
  * Singleton Excel processor instance.
  * Use this for standard Excel processing operations.

package/dist/processors/document/ExcelProcessor.js

@@ -39,6 +39,7 @@ import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
 import { SIZE_LIMITS } from "../config/index.js";
 import { FileErrorCode } from "../errors/index.js";
 import { tryImport } from "../../utils/tryImport.js";
+import { dedupeColumnNames } from "../../utils/csvProcessor.js";
 let _exceljs = null;
 async function loadExcelJS() {
     if (_exceljs) {
@@ -482,6 +483,123 @@ export class ExcelProcessor extends BaseFileProcessor {
     }
 }
 // =============================================================================
+// PROMPT FORMATTING
+// =============================================================================
+/** Rows beyond this per sheet are summarised rather than listed. */
+const PROMPT_PREVIEW_ROWS = 20;
+/** RFC 4180: quote a field that contains a comma, quote or newline. */
+function csvEscape(value) {
+    return /[",\r\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+/** A pipe inside a cell would otherwise split it into two columns. */
+function markdownEscape(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/\|/g, "\\|")
+        .replace(/\r?\n/g, " ");
+}
+function cellText(value) {
+    return String(value ?? "");
+}
+function formatSheetRows(sheet, formatStyle) {
+    const previewRows = sheet.rows.slice(0, PROMPT_PREVIEW_ROWS);
+    if (previewRows.length === 0) {
+        return "";
+    }
+    switch (formatStyle) {
+        case "markdown": {
+            // `rows[0]` IS the header row (that is where `headers` came from), so
+            // the body always starts at index 1 — emitting row 0 again would
+            // duplicate the header underneath the separator.
+            const header = sheet.headers.length > 0 ? sheet.headers : previewRows[0].map(cellText);
+            const body = previewRows.slice(1);
+            const columnCount = Math.max(header.length, ...body.map((row) => row.length), 1);
+            const pad = (cells) => Array.from({ length: columnCount }, (_, i) => markdownEscape(cells[i] ?? ""));
+            return [
+                `| ${pad(header).join(" | ")} |`,
+                `| ${Array.from({ length: columnCount }, () => "---").join(" | ")} |`,
+                ...body.map((row) => `| ${pad(row.map(cellText)).join(" | ")} |`),
+            ].join("\n");
+        }
+        case "csv":
+            return previewRows
+                .map((row) => row.map((cell) => csvEscape(cellText(cell))).join(","))
+                .join("\n");
+        case "json": {
+            const rawHeader = sheet.headers.length > 0 ? sheet.headers : previewRows[0].map(cellText);
+            const body = previewRows.slice(1);
+            // A data row's own populated-cell count can exceed the header's — row
+            // extraction sizes each row on its own last populated cell, not a
+            // workbook-wide column count, so a header truncated by a merged cell
+            // (or a value landing in a column the header left blank) is a normal
+            // spreadsheet shape. "markdown" already sizes on the widest row for
+            // exactly this reason; do the same here instead of zipping strictly to
+            // header.length, which silently dropped every cell past it.
+            const columnCount = Math.max(rawHeader.length, ...body.map((row) => row.length), 1);
+            const extendedHeader = Array.from({ length: columnCount }, (_, i) => rawHeader[i] ?? `Column ${i + 1}`);
+            // Object.fromEntries silently drops a column when two header cells are
+            // literally the same string (a copy-pasted header, a merged-and-split
+            // sheet) — the later column's value overwrites the earlier one under
+            // the shared key. Dedupe first so every column keeps its own key.
+            const header = dedupeColumnNames(extendedHeader);
+            const objects = body.map((row) => Object.fromEntries(header.map((key, i) => [key, row[i] ?? null])));
+            return JSON.stringify(objects, null, 2);
+        }
+        case "raw":
+        default:
+            // Bug-for-bug with the pre-option behaviour: the header line is printed
+            // and then `rows` is printed in full, so row 1 appears twice. Callers
+            // that want a clean table ask for "markdown" or "csv".
+            return [
+                sheet.headers.join("\t"),
+                ...previewRows.map((row) => row.map(cellText).join("\t")),
+            ].join("\n");
+    }
+}
+/**
+ * Render processed worksheets into the text handed to the model.
+ *
+ * @param worksheets - Worksheets extracted from the workbook
+ * @param totalRows - Total row count across all extracted worksheets
+ * @param options - Office options; `sheetName` selects a single sheet and
+ *   `formatStyle` chooses the rendering (default `raw`, the tab-separated
+ *   preview that predates the option)
+ * @returns Prompt-ready text, or a message naming the available sheets when
+ *   `sheetName` matches none of them
+ */
+export function formatWorksheetsForPrompt(worksheets, totalRows, options) {
+    const requested = options?.sheetName;
+    let selected = worksheets;
+    if (requested !== undefined) {
+        selected = worksheets.filter((sheet) => sheet.name === requested);
+        if (selected.length === 0) {
+            const available = worksheets.map((sheet) => sheet.name).join(", ");
+            return `Sheet "${requested}" not found. Available sheets: ${available || "(none)"}`;
+        }
+    }
+    const formatStyle = options?.formatStyle ?? "raw";
+    const selectedRows = selected.reduce((sum, sheet) => sum + sheet.rowCount, 0);
+    const scope = requested !== undefined
+        ? `Spreadsheet: sheet "${requested}" of ${worksheets.length}, ${selectedRows} rows`
+        : `Spreadsheet: ${worksheets.length} sheet(s), ${totalRows} total rows`;
+    let text = `${scope}\n`;
+    for (const sheet of selected) {
+        text += `\n### Sheet: ${sheet.name}\n`;
+        text += `Columns (${sheet.columnCount}): ${sheet.headers.join(", ")}\n`;
+        text += `Rows: ${sheet.rowCount}\n`;
+        const rendered = formatSheetRows(sheet, formatStyle);
+        if (!rendered) {
+            continue;
+        }
+        text += `\nData:\n${rendered}\n`;
+        const remaining = sheet.rowCount - PROMPT_PREVIEW_ROWS;
+        if (remaining > 0) {
+            text += `... (${remaining} more rows)\n`;
+        }
+    }
+    return text;
+}
+// =============================================================================
 // SINGLETON INSTANCE
 // =============================================================================
 /**

package/dist/processors/document/WordProcessor.js

@@ -35,6 +35,7 @@ import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
 import { SIZE_LIMITS } from "../config/index.js";
 import { FileErrorCode } from "../errors/index.js";
 import { tryImport } from "../../utils/tryImport.js";
+import { htmlToMarkdown } from "../../utils/htmlToMarkdown.js";
 let _mammoth = null;
 async function loadMammoth() {
     if (_mammoth) {
@@ -64,6 +65,22 @@ const SUPPORTED_WORD_EXTENSIONS = [".docx", ".doc"];
  * Word documents can be larger due to embedded images and complex formatting
  */
 const WORD_TIMEOUT_MS = 60000;
+/**
+ * Derive the document metrics from the extracted plain text.
+ *
+ * Counted off `textContent` rather than the markdown so the numbers describe
+ * the document's prose, not the syntax added to represent it.
+ */
+function measureText(textContent) {
+    const trimmed = textContent.trim();
+    return {
+        wordCount: trimmed ? trimmed.split(/\s+/).length : 0,
+        paragraphCount: textContent
+            .split(/\n+/)
+            .filter((line) => line.trim().length > 0).length,
+        characterCount: textContent.length,
+    };
+}
 // =============================================================================
 // WORD PROCESSOR CLASS
 // =============================================================================
@@ -144,7 +161,9 @@ export class WordProcessor extends BaseFileProcessor {
         return {
             textContent: "",
             htmlContent: "",
+            markdownContent: "",
             warnings: [],
+            ...measureText(""),
             buffer,
             mimetype: fileInfo.mimetype ||
                 "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
@@ -267,7 +286,9 @@ export class WordProcessor extends BaseFileProcessor {
                     filename: this.getFilename(fileInfo),
                     textContent,
                     htmlContent,
+                    markdownContent: htmlToMarkdown(htmlContent),
                     warnings,
+                    ...measureText(textContent),
                 },
             };
         }

package/dist/types/file.d.ts

@@ -611,6 +611,21 @@ export type OfficeProcessorOptions = {
     processAllSheets?: boolean;
     /** For presentations (pptx only): whether to include slide notes */
     includeSlideNotes?: boolean;
+    /**
+     * For spreadsheets (xlsx only): restrict processing to the named sheet.
+     * When the workbook has no sheet by that name the result says so and lists
+     * the names it does have, rather than silently falling back to every sheet.
+     * Omit to process every sheet (the default).
+     */
+    sheetName?: string;
+    /**
+     * For spreadsheets (xlsx only): how sheet data is rendered into the prompt.
+     * - `raw` (default): tab-separated preview — the long-standing behaviour
+     * - `csv`: comma-separated values with RFC 4180 quoting
+     * - `markdown`: a markdown table per sheet
+     * - `json`: an array of row objects keyed by the header row
+     */
+    formatStyle?: "raw" | "markdown" | "json" | "csv";
 };
 /**
  * File detector options

package/dist/types/generate.d.ts

@@ -18,7 +18,7 @@ import type { AvatarOptions, AvatarResult } from "./avatar.js";
 import type { MusicOptions, MusicResult } from "./music.js";
 import type { StandardRecord, ValidationSchema, ZodUnknownSchema } from "./aliases.js";
 import type { NeurolinkCredentials } from "./providers.js";
-import type { CSVProcessorOptions, VideoProcessorOptions, FileWithMetadata, MultimodalAudioEntry, MultimodalVideoEntry, VisionImageOutputFormat } from "./file.js";
+import type { CSVProcessorOptions, VideoProcessorOptions, OfficeProcessorOptions, FileWithMetadata, MultimodalAudioEntry, MultimodalVideoEntry, VisionImageOutputFormat } from "./file.js";
 import type { WorkflowConfig } from "./workflow.js";
 import type { Schema, Tool, ToolChoice } from "./tools.js";
 import type { StepResult, LanguageModel } from "./providers.js";
@@ -150,6 +150,11 @@ export type GenerateOptions = {
         music?: MusicOptions;
     };
     csvOptions?: CSVProcessorOptions;
+    /**
+     * Office document processing options. Currently consumed by the XLSX path
+     * (`sheetName`, `formatStyle`); see OfficeProcessorOptions.
+     */
+    officeOptions?: OfficeProcessorOptions;
     /** PDF processing options (#258). */
     pdfOptions?: {
         /** Password for an encrypted PDF (image-conversion fallback path). */
@@ -1437,6 +1442,11 @@ export type TextGenerationOptions = {
      * saying so.
      */
     videoOptions?: VideoProcessorOptions;
+    /**
+     * Office document processing options. Currently consumed by the XLSX path
+     * (`sheetName`, `formatStyle`); see OfficeProcessorOptions.
+     */
+    officeOptions?: OfficeProcessorOptions;
     /** PDF processing options (#258). */
     pdfOptions?: {
         /** Password for an encrypted PDF (image-conversion fallback path). */

package/dist/types/processor.d.ts

@@ -639,8 +639,19 @@ export type ProcessedWord = ProcessedFileBase & {
     textContent: string;
     /** HTML representation of the Word document */
     htmlContent: string;
+    /**
+     * Markdown rendering of `htmlContent`, preserving the structure that plain
+     * text loses: headings, ordered/unordered lists and tables.
+     */
+    markdownContent: string;
     /** Warnings from mammoth extraction (e.g., unsupported elements) */
     warnings: string[];
+    /** Whitespace-delimited word count of `textContent`. */
+    wordCount: number;
+    /** Count of non-empty text blocks in `textContent`. */
+    paragraphCount: number;
+    /** Character count of `textContent`, including whitespace. */
+    characterCount: number;
 };
 /**
  * Processed RTF document result.

package/dist/types/stream.d.ts

@@ -16,7 +16,7 @@ import type { AIModelProviderConfig, NeurolinkCredentials } from "./providers.js
 import type { TTSChunk, TTSOptions, TTSResult } from "./tts.js";
 import type { STTOptions, STTResult } from "./stt.js";
 import type { StandardRecord, ValidationSchema } from "./aliases.js";
-import type { CSVProcessorOptions, FileWithMetadata, VideoProcessorOptions, VisionImageOutputFormat } from "./file.js";
+import type { CSVProcessorOptions, FileWithMetadata, VideoProcessorOptions, VisionImageOutputFormat, OfficeProcessorOptions } from "./file.js";
 import type { WorkflowConfig } from "./workflow.js";
 import type { LanguageModel, StepResult } from "./providers.js";
 import type { Tool, ToolChoice } from "./tools.js";
@@ -366,6 +366,11 @@ export type StreamOptions = {
      * saying so.
      */
     videoOptions?: VideoProcessorOptions;
+    /**
+     * Office document processing options. Currently consumed by the XLSX path
+     * (`sheetName`, `formatStyle`); see OfficeProcessorOptions.
+     */
+    officeOptions?: OfficeProcessorOptions;
     /** PDF processing options (#258). */
     pdfOptions?: {
         /** Password for an encrypted PDF (image-conversion fallback path). */

package/dist/types/utilities.d.ts

@@ -321,3 +321,22 @@ export type ScalarRecoveryDecision = {
 } | {
     kind: "not-json";
 };
+/**
+ * An element in the parsed HTML tree used for Markdown conversion.
+ */
+export type MarkdownHtmlElementNode = {
+    kind: "element";
+    /** Lower-cased tag name. */
+    tag: string;
+    /** Lower-cased attribute names mapped to their decoded values. */
+    attrs: Record<string, string>;
+    children: MarkdownHtmlNode[];
+};
+/**
+ * A node in the parsed HTML tree used for Markdown conversion: either a text
+ * run or an element.
+ */
+export type MarkdownHtmlNode = {
+    kind: "text";
+    value: string;
+} | MarkdownHtmlElementNode;

package/dist/utils/fileDetector.js

@@ -341,14 +341,14 @@ 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, options?.videoOptions);
+                const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider, options?.videoOptions, options?.officeOptions);
                 FileDetector.setFileResultSpanAttributes(span, result, inputFilename, detection.type);
                 return result;
             }
             const content = loadedUrl?.content ??
                 (await FileDetector.loadContent(input, detection, options));
             const csvOptions = options?.csvOptions;
-            const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider, options?.videoOptions);
+            const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider, options?.videoOptions, options?.officeOptions);
             FileDetector.setFileResultSpanAttributes(span, result, inputFilename, detection.type);
             return result;
         });
@@ -1063,7 +1063,7 @@ export class FileDetector {
     /**
      * Route to appropriate processor
      */
-    static async processFile(content, detection, options, provider, videoOptions) {
+    static async processFile(content, detection, options, provider, videoOptions, officeOptions) {
         switch (detection.type) {
             case "csv":
                 // Pass original extension through to CSV processor; if detection has none,
@@ -1087,7 +1087,7 @@ export class FileDetector {
             case "archive":
                 return await FileDetector.processArchiveFile(content, detection);
             case "xlsx":
-                return await FileDetector.processXlsxFile(content, detection);
+                return await FileDetector.processXlsxFile(content, detection, officeOptions);
             case "docx":
                 return await FileDetector.processDocxFile(content, detection);
             case "pptx":
@@ -1283,7 +1283,7 @@ export class FileDetector {
     /**
      * Process Excel/OpenDocument spreadsheet file via ExcelProcessor or OpenDocumentProcessor
      */
-    static async processXlsxFile(content, detection) {
+    static async processXlsxFile(content, detection, officeOptions) {
         const xlsxFilename = detection.metadata.filename || "spreadsheet";
         try {
             const ext = detection.extension?.toLowerCase();
@@ -1308,7 +1308,7 @@ export class FileDetector {
                 }
             }
             else {
-                const { excelProcessor } = await import("../processors/document/ExcelProcessor.js");
+                const { excelProcessor, formatWorksheetsForPrompt } = await import("../processors/document/ExcelProcessor.js");
                 const xlsxResult = await excelProcessor.processFile({
                     id: xlsxFilename,
                     name: xlsxFilename,
@@ -1318,30 +1318,9 @@ export class FileDetector {
                     buffer: content,
                 });
                 if (xlsxResult.success && xlsxResult.data) {
-                    // Build text content from worksheets
-                    const sheets = xlsxResult.data.worksheets || [];
-                    let textContent = `Spreadsheet: ${sheets.length} sheet(s), ${xlsxResult.data.totalRows} total rows\n`;
-                    for (const sheet of sheets) {
-                        textContent += `\n### Sheet: ${sheet.name}\n`;
-                        textContent += `Columns (${sheet.columnCount}): ${sheet.headers.join(", ")}\n`;
-                        textContent += `Rows: ${sheet.rowCount}\n`;
-                        // Include first rows as sample data
-                        const sampleRows = sheet.rows.slice(0, 20);
-                        const rowText = sampleRows
-                            .map((row) => row.map((c) => String(c ?? "")).join("\t"))
-                            .join("\n");
-                        if (!rowText) {
-                            continue;
-                        }
-                        textContent += `\nData:\n${sheet.headers.join("\t")}\n${rowText}\n`;
-                        const remaining = sheet.rowCount - 20;
-                        if (remaining > 0) {
-                            textContent += `... (${remaining} more rows)\n`;
-                        }
-                    }
                     return {
                         type: "xlsx",
-                        content: textContent,
+                        content: formatWorksheetsForPrompt(xlsxResult.data.worksheets || [], xlsxResult.data.totalRows, officeOptions),
                         mimeType: detection.mimeType,
                         metadata: detection.metadata,
                     };
@@ -1374,13 +1353,18 @@ export class FileDetector {
         try {
             if (ext === "odt") {
                 const { openDocumentProcessor } = await import("../processors/document/OpenDocumentProcessor.js");
-                const odtResult = await openDocumentProcessor.processFile({
+                // Bounded per the project's async-timeout guideline, matching the ODP
+                // branch of processPptxFile below: this unzips and parses
+                // attacker-supplied bytes, and a stalled parse would otherwise hold
+                // the request open with no ceiling. On timeout the throw lands in
+                // this block's existing catch, which degrades to the placeholder.
+                const odtResult = await withTimeout(openDocumentProcessor.processFile({
                     id: docxFilename,
                     name: docxFilename,
                     mimetype: detection.mimeType || "application/vnd.oasis.opendocument.text",
                     size: content.length,
                     buffer: content,
-                });
+                }), FileDetector.DEFAULT_DOCUMENT_TIMEOUT);
                 if (odtResult.success && odtResult.data) {
                     return {
                         type: "docx",
@@ -1393,13 +1377,14 @@ export class FileDetector {
             }
             else if (ext === "rtf") {
                 const { rtfProcessor } = await import("../processors/document/RtfProcessor.js");
-                const rtfResult = await rtfProcessor.processFile({
+                // Bounded for the same reason as the odt branch above.
+                const rtfResult = await withTimeout(rtfProcessor.processFile({
                     id: docxFilename,
                     name: docxFilename,
                     mimetype: detection.mimeType || "application/rtf",
                     size: content.length,
                     buffer: content,
-                });
+                }), FileDetector.DEFAULT_DOCUMENT_TIMEOUT);
                 if (rtfResult.success && rtfResult.data) {
                     return {
                         type: "docx",
@@ -1412,19 +1397,29 @@ export class FileDetector {
             }
             else {
                 const { wordProcessor } = await import("../processors/document/WordProcessor.js");
-                const docxResult = await wordProcessor.processFile({
+                // Bounded for the same reason as the odt branch above. This call now
+                // also runs htmlToMarkdown's recursive HTML-to-markdown rendering
+                // over mammoth's output, so it is real additional work inside what
+                // was already an unbounded call.
+                const docxResult = await withTimeout(wordProcessor.processFile({
                     id: docxFilename,
                     name: docxFilename,
                     mimetype: detection.mimeType ||
                         "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
                     size: content.length,
                     buffer: content,
-                });
+                }), FileDetector.DEFAULT_DOCUMENT_TIMEOUT);
                 if (docxResult.success && docxResult.data) {
+                    // Prefer the markdown rendering: it keeps the headings, lists and
+                    // tables that the plain-text extraction flattens away. Plain text
+                    // remains the fallback for a document with no convertible structure.
+                    const { markdownContent, textContent, wordCount, paragraphCount, characterCount, } = docxResult.data;
+                    const body = markdownContent || textContent;
                     return {
                         type: "docx",
-                        content: docxResult.data.textContent ||
-                            FileDetector.formatInformativePlaceholder("Document", docxFilename, content, detection),
+                        content: body
+                            ? `Document: ${wordCount} words, ${paragraphCount} paragraphs, ${characterCount} characters\n\n${body}`
+                            : FileDetector.formatInformativePlaceholder("Document", docxFilename, content, detection),
                         mimeType: detection.mimeType,
                         metadata: detection.metadata,
                     };

package/dist/utils/htmlToMarkdown.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HTML to Markdown conversion for document processors.
+ *
+ * Scoped deliberately to the small, well-formed HTML subset that document
+ * converters emit (mammoth for DOCX): headings, paragraphs, emphasis, links,
+ * images, lists, block quotes, preformatted text and tables. It is not a
+ * general-purpose web-page converter, which is why the repository gains no
+ * dependency for it.
+ *
+ * @module utils/htmlToMarkdown
+ */
+/**
+ * Convert an HTML fragment to Markdown.
+ *
+ * @param html - HTML produced by a document converter
+ * @returns Markdown text, or an empty string when the fragment has no content
+ *
+ * @example
+ * ```typescript
+ * htmlToMarkdown("<h1>Title</h1><p>Body</p>"); // "# Title\n\nBody"
+ * ```
+ */
+export declare function htmlToMarkdown(html: string): string;