@juspay/neurolink 9.94.5 → 9.94.7

package/dist/cli/factories/commandFactory.d.ts

@@ -24,8 +24,6 @@ export declare class CLICommandFactory {
     private static processCliPDFFiles;
     private static processCliFiles;
     private static processCliVideoFiles;
-    private static isNonLocalFileReference;
-    private static validateCliInputFiles;
     private static processOptions;
     /**
      * Validate Anthropic subscription options

package/dist/cli/factories/commandFactory.js

@@ -24,6 +24,7 @@ import { initializeCliParser } from "../parser.js";
 import { formatFileSize, saveAudioToFile } from "../utils/audioFileUtils.js";
 import { playAudio } from "../utils/audioPlayer.js";
 import { resolveFilePaths } from "../utils/pathResolver.js";
+import { validateCliInputFiles, validateCsvMaxRows, } from "../utils/inputValidation.js";
 import { animatedWrite } from "../utils/typewriter.js";
 import { createStreamAbortHandler } from "../utils/abortHandler.js";
 import { formatVideoFileSize, getVideoMetadataSummary, saveVideoToFile, } from "../utils/videoFileUtils.js";
@@ -187,7 +188,7 @@ export class CLICommandFactory {
         csvMaxRows: {
             type: "number",
             default: 1000,
-            description: "Maximum number of CSV rows to process",
+            description: "Maximum number of CSV rows to process (positive integer, range 1-100000, default 1000)",
         },
         csvFormat: {
             type: "string",
@@ -805,42 +806,6 @@ export class CLICommandFactory {
         // URLs are preserved as-is by resolveFilePaths
         return resolveFilePaths(paths);
     }
-    static isNonLocalFileReference(filePath) {
-        const lower = filePath.toLowerCase();
-        return (lower.startsWith("http://") ||
-            lower.startsWith("https://") ||
-            lower.startsWith("file://") ||
-            lower.startsWith("data:"));
-    }
-    static validateCliInputFiles(argv) {
-        const fileArgs = [
-            { option: "--image", value: argv.image },
-            { option: "--csv", value: argv.csv },
-            { option: "--pdf", value: argv.pdf },
-            { option: "--video", value: argv.video },
-            { option: "--file", value: argv.file },
-        ];
-        const missingPaths = [];
-        for (const { option, value } of fileArgs) {
-            if (!value) {
-                continue;
-            }
-            const rawPaths = Array.isArray(value) ? value : [value];
-            const resolvedPaths = resolveFilePaths(rawPaths);
-            for (let i = 0; i < resolvedPaths.length; i++) {
-                const resolvedPath = resolvedPaths[i];
-                if (CLICommandFactory.isNonLocalFileReference(resolvedPath)) {
-                    continue;
-                }
-                if (!fs.existsSync(resolvedPath)) {
-                    missingPaths.push(`${option} path not found: ${rawPaths[i]} (resolved to ${resolvedPath})`);
-                }
-            }
-        }
-        if (missingPaths.length > 0) {
-            throw new Error(`One or more input files do not exist:\n${missingPaths.join("\n")}`);
-        }
-    }
     // Helper method to process common options
     static processOptions(argv) {
         // Handle noColor option by disabling chalk
@@ -1538,7 +1503,12 @@ export class CLICommandFactory {
                     .example('$0 generate "Smooth camera movement" --image ./input.jpg --provider vertex --model veo-3.1-generate-001 --outputMode video --videoResolution 720p --videoLength 6 --videoAspectRatio 16:9 --videoOutput ./output.mp4', "Video generation with full options")
                     .example('$0 generate "AI in Healthcare" --pptPages 10', "Generate a PowerPoint presentation")
                     .example('$0 generate "Company Q4 Results" --pptPages 15 --pptTheme corporate --pptAudience business', "Generate presentation with options")
-                    .example('$0 generate "Machine Learning 101" --pptTheme minimal --pptTone educational --pptNoImages', "Generate educational slides without AI images"));
+                    .example('$0 generate "Machine Learning 101" --pptTheme minimal --pptTone educational --pptNoImages', "Generate educational slides without AI images")
+                    .example('$0 generate "Describe this image" --image ./photo.jpg', "Analyze an image (multimodal input)")
+                    .example('$0 generate "Summarize this report" --pdf ./report.pdf', "Analyze a PDF document")
+                    .example('$0 generate "Key trends?" --csv large-data.csv --csvMaxRows 100', "Analyze a CSV with a row limit")
+                    .example('$0 generate "Compare the chart and the report" --image ./chart.png --pdf ./report.pdf', "Combine multiple file types in one prompt")
+                    .example('$0 generate "What is in this file?" --file ./data.json', "Auto-detect a file type with --file"));
             },
             handler: async (argv) => await CLICommandFactory.executeGenerate(argv),
         };
@@ -1560,7 +1530,10 @@ export class CLICommandFactory {
                     .example('$0 stream "Explain machine learning" -p anthropic', "Stream with specific provider")
                     .example('$0 stream "Code walkthrough" --output story.txt', "Stream to file")
                     .example('echo "Live demo" | $0 stream', "Stream from stdin")
-                    .example('$0 stream "Narrate this video" --video path/to/video.mp4', "Stream video analysis"));
+                    .example('$0 stream "Narrate this video" --video path/to/video.mp4', "Stream video analysis")
+                    .example('$0 stream "Describe this image" --image ./photo.jpg', "Stream image analysis (multimodal input)")
+                    .example('$0 stream "Summarize this document" --pdf ./report.pdf', "Stream PDF analysis")
+                    .example('$0 stream "Explain this dataset" --csv ./data.csv --csv-format markdown', "Stream CSV analysis"));
             },
             handler: async (argv) => await CLICommandFactory.executeStream(argv),
         };
@@ -2277,7 +2250,11 @@ export class CLICommandFactory {
                 if (isSttOnly) {
                     return "";
                 }
-                throw new Error("No input received from stdin");
+                throw new Error("❌ No input received from stdin.\n" +
+                    "💡 Try this:\n" +
+                    '   neurolink generate "your prompt"\n' +
+                    '   echo "your prompt" | neurolink generate\n' +
+                    '   neurolink generate "Describe this image" --image ./photo.jpg');
             }
             return trimmedData;
         }
@@ -2285,7 +2262,11 @@ export class CLICommandFactory {
             if (isSttOnly) {
                 return "";
             }
-            throw new Error('Input required. Use: neurolink generate "your prompt" or echo "prompt" | neurolink generate');
+            throw new Error("❌ Input required.\n" +
+                "💡 Try this:\n" +
+                '   neurolink generate "your prompt"\n' +
+                '   echo "your prompt" | neurolink generate\n' +
+                '   neurolink generate "Describe this image" --image ./photo.jpg');
         }
         return argv.input;
     }
@@ -2544,7 +2525,8 @@ export class CLICommandFactory {
             if (options.delay) {
                 await new Promise((resolve) => setTimeout(resolve, options.delay));
             }
-            CLICommandFactory.validateCliInputFiles(argv);
+            validateCliInputFiles(argv);
+            validateCsvMaxRows(argv);
             // Process context
             const { inputText, contextMetadata } = CLICommandFactory.processGenerateContext(rawInput, options);
             // Handle dry-run mode for testing
@@ -3304,7 +3286,11 @@ export class CLICommandFactory {
                     argv.input = "";
                     return;
                 }
-                throw new Error("No input received from stdin");
+                throw new Error("❌ No input received from stdin.\n" +
+                    "💡 Try this:\n" +
+                    '   neurolink stream "your prompt"\n' +
+                    '   echo "your prompt" | neurolink stream\n' +
+                    '   neurolink stream "Describe this image" --image ./photo.jpg');
             }
         }
         else if (!argv.input) {
@@ -3312,7 +3298,11 @@ export class CLICommandFactory {
                 argv.input = "";
                 return;
             }
-            throw new Error('Input required. Use: neurolink stream "your prompt" or echo "prompt" | neurolink stream');
+            throw new Error("❌ Input required.\n" +
+                "💡 Try this:\n" +
+                '   neurolink stream "your prompt"\n' +
+                '   echo "your prompt" | neurolink stream\n' +
+                '   neurolink stream "Describe this image" --image ./photo.jpg');
         }
     }
     /**
@@ -3331,7 +3321,8 @@ export class CLICommandFactory {
             if (options.delay) {
                 await new Promise((resolve) => setTimeout(resolve, options.delay));
             }
-            CLICommandFactory.validateCliInputFiles(argv);
+            validateCliInputFiles(argv);
+            validateCsvMaxRows(argv);
             const { inputText, contextMetadata } = await CLICommandFactory.processStreamContext(argv, options);
             // Handle dry-run mode for testing
             if (options.dryRun) {

package/dist/cli/loop/session.js

@@ -414,6 +414,22 @@ export class LoopSession {
             logger.always(chalk.yellow(`  ${c.cmd.padEnd(20)}`) + `${c.desc}`);
         });
         logger.always("\nAny other command will be executed as a standard neurolink CLI command.");
+        // #315: multimodal file flags are buried in the raw yargs dump below — call
+        // them out explicitly so loop users know PDFs/images/CSVs/video are supported.
+        logger.always(chalk.cyan("\nMultimodal file inputs (per-command flags):"));
+        [
+            ["--image <path|url>", "Attach an image for analysis (repeatable)"],
+            ["--pdf <path|url>", "Attach a PDF document (repeatable)"],
+            [
+                "--csv <path|url>",
+                "Attach a CSV file (see --csv-format, --csv-max-rows)",
+            ],
+            ["--video <path|url>", "Attach a video for analysis"],
+            ["--file <path|url>", "Attach a file and auto-detect its type"],
+        ].forEach(([flag, desc]) => {
+            logger.always(chalk.yellow(`  ${flag.padEnd(20)}`) + `${desc}`);
+        });
+        logger.always(chalk.gray('  e.g.  generate "Describe this" --image ./photo.jpg --pdf ./report.pdf'));
         // Also show the standard help output
         this.initializeCliParser().showHelp("log");
     }
@@ -429,6 +445,11 @@ export class LoopSession {
                 logger.always(chalk.gray(`    Type: ${schema.type}`));
             }
         }
+        // #350: multimodal file inputs are per-command flags, not session variables,
+        // so they don't appear above — point users to them explicitly.
+        logger.always(chalk.gray("\n  Note: file inputs (--image/--pdf/--csv/--video/--file) are per-command\n" +
+            "  flags, not session variables — pass them directly on a generate/stream line,\n" +
+            '  e.g.  generate "Summarize this" --pdf ./report.pdf'));
     }
     /**
      * Get command input with history support using readline

package/dist/cli/utils/inputValidation.d.ts

@@ -0,0 +1,38 @@
+/**
+ * CLI Input Validation Utilities
+ *
+ * Validates multimodal file flags (--image/--csv/--pdf/--video/--file) and
+ * --csv-max-rows before a generate/stream/batch run starts, so bad input
+ * fails fast with a clear message instead of surfacing deep inside provider
+ * calls. Exported as standalone functions (rather than private statics on
+ * CLICommandFactory) so callers — including tests — can import and invoke
+ * them directly, without reaching into the class via an `unknown` cast.
+ */
+/**
+ * Soft (warn-only) size thresholds for CLI multimodal flags. Intentionally
+ * defined here rather than reusing `lib/processors/config/sizeLimits.ts`'s
+ * hard processor caps (e.g. PDF's 100MB hard limit): reusing those names/
+ * values would couple the CLI layer to processor internals across the
+ * CLI/SDK boundary, and would blur the line between a soft "this may be
+ * slow" warning and the actual hard cap the processor enforces.
+ */
+export declare const CLI_SOFT_LIMITS_MB: {
+    readonly IMAGE_MAX_MB: 10;
+    readonly CSV_MAX_MB: 50;
+    readonly PDF_MAX_MB: 100;
+    readonly VIDEO_MAX_MB: 500;
+};
+/**
+ * Validate --image/--csv/--pdf/--video/--file inputs before a CLI run
+ * starts: every local path must exist, must not be a directory, and — for
+ * the flags with a soft limit — triggers a size warning above the
+ * threshold. URLs/data URIs skip both existence and size checks (#319).
+ */
+export declare function validateCliInputFiles(argv: Record<string, unknown>): void;
+/**
+ * #310: validate --csv-max-rows is a positive integer in the range
+ * 1-100000, matching the documented option range (the value previously
+ * flowed through silently, or — above 100000 — only warned instead of
+ * being rejected, contradicting the documented hard range).
+ */
+export declare function validateCsvMaxRows(argv: Record<string, unknown>): void;

package/dist/cli/utils/inputValidation.js

@@ -0,0 +1,143 @@
+/**
+ * CLI Input Validation Utilities
+ *
+ * Validates multimodal file flags (--image/--csv/--pdf/--video/--file) and
+ * --csv-max-rows before a generate/stream/batch run starts, so bad input
+ * fails fast with a clear message instead of surfacing deep inside provider
+ * calls. Exported as standalone functions (rather than private statics on
+ * CLICommandFactory) so callers — including tests — can import and invoke
+ * them directly, without reaching into the class via an `unknown` cast.
+ */
+import fs from "node:fs";
+import chalk from "chalk";
+import { logger } from "../../lib/utils/logger.js";
+import { resolveFilePaths } from "./pathResolver.js";
+/**
+ * Soft (warn-only) size thresholds for CLI multimodal flags. Intentionally
+ * defined here rather than reusing `lib/processors/config/sizeLimits.ts`'s
+ * hard processor caps (e.g. PDF's 100MB hard limit): reusing those names/
+ * values would couple the CLI layer to processor internals across the
+ * CLI/SDK boundary, and would blur the line between a soft "this may be
+ * slow" warning and the actual hard cap the processor enforces.
+ */
+export const CLI_SOFT_LIMITS_MB = {
+    IMAGE_MAX_MB: 10,
+    CSV_MAX_MB: 50,
+    PDF_MAX_MB: 100,
+    VIDEO_MAX_MB: 500,
+};
+function isNonLocalFileReference(filePath) {
+    const lower = filePath.toLowerCase();
+    return (lower.startsWith("http://") ||
+        lower.startsWith("https://") ||
+        lower.startsWith("file://") ||
+        lower.startsWith("data:"));
+}
+/**
+ * Validate --image/--csv/--pdf/--video/--file inputs before a CLI run
+ * starts: every local path must exist, must not be a directory, and — for
+ * the flags with a soft limit — triggers a size warning above the
+ * threshold. URLs/data URIs skip both existence and size checks (#319).
+ */
+export function validateCliInputFiles(argv) {
+    const fileArgs = [
+        {
+            option: "--image",
+            value: argv.image,
+            warnAtMB: CLI_SOFT_LIMITS_MB.IMAGE_MAX_MB,
+        },
+        {
+            option: "--csv",
+            value: argv.csv,
+            warnAtMB: CLI_SOFT_LIMITS_MB.CSV_MAX_MB,
+        },
+        {
+            option: "--pdf",
+            value: argv.pdf,
+            warnAtMB: CLI_SOFT_LIMITS_MB.PDF_MAX_MB,
+        },
+        {
+            option: "--video",
+            value: argv.video,
+            warnAtMB: CLI_SOFT_LIMITS_MB.VIDEO_MAX_MB,
+        },
+        { option: "--file", value: argv.file },
+    ];
+    const missingPaths = [];
+    for (const { option, value, warnAtMB } of fileArgs) {
+        if (!value) {
+            continue;
+        }
+        const rawPaths = Array.isArray(value) ? value : [value];
+        const resolvedPaths = resolveFilePaths(rawPaths);
+        for (let i = 0; i < resolvedPaths.length; i++) {
+            const resolvedPath = resolvedPaths[i];
+            // URLs / data: refs skip both existence and size checks (#319).
+            if (isNonLocalFileReference(resolvedPath)) {
+                continue;
+            }
+            // Single statSync covers existence, directory rejection, and the
+            // size warning below — avoids a second syscall and closes the
+            // TOCTOU gap a separate existsSync()+statSync() pair would leave.
+            let stat;
+            try {
+                stat = fs.statSync(resolvedPath);
+            }
+            catch (err) {
+                // Only ENOENT actually means "not found" — EACCES (permission
+                // denied), ELOOP (symlink loop), ENOTDIR, etc. are real failures
+                // that get masked (and made undebuggable) if we blanket-label
+                // every statSync error the same way.
+                const code = err?.code;
+                if (code === "ENOENT") {
+                    missingPaths.push(`${option} path not found: ${rawPaths[i]} (resolved to ${resolvedPath})`);
+                }
+                else {
+                    const reason = err instanceof Error ? err.message : String(err);
+                    missingPaths.push(`${option} path could not be accessed: ${rawPaths[i]} (resolved to ${resolvedPath}) — ` +
+                        `${code ? `${code}: ` : ""}${reason}`);
+                }
+                continue;
+            }
+            if (stat.isDirectory()) {
+                missingPaths.push(`${option} path is a directory, not a file: ${rawPaths[i]} (resolved to ${resolvedPath})`);
+                continue;
+            }
+            // #319: warn (not error) when a local multimodal file is unusually
+            // large so the user isn't surprised by slow processing / token blowups.
+            if (warnAtMB !== undefined) {
+                const sizeMB = stat.size / (1024 * 1024);
+                if (sizeMB > warnAtMB) {
+                    logger.always(chalk.yellow(`⚠️  ${option} file ${rawPaths[i]} is ${sizeMB.toFixed(1)}MB ` +
+                        `(above the ${warnAtMB}MB soft limit) — processing may be slow ` +
+                        `or exceed provider token/size limits.`));
+                }
+            }
+        }
+    }
+    if (missingPaths.length > 0) {
+        throw new Error("❌ One or more input files are invalid:\n" +
+            `${missingPaths.join("\n")}\n` +
+            "💡 Check the path is correct and relative to your current directory, " +
+            "or pass an absolute path / URL.");
+    }
+}
+/**
+ * #310: validate --csv-max-rows is a positive integer in the range
+ * 1-100000, matching the documented option range (the value previously
+ * flowed through silently, or — above 100000 — only warned instead of
+ * being rejected, contradicting the documented hard range).
+ */
+export function validateCsvMaxRows(argv) {
+    const raw = argv.csvMaxRows;
+    if (raw === undefined) {
+        return;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > 100000) {
+        throw new Error(`Invalid --csv-max-rows (--csvMaxRows) value: ${String(raw)}. ` +
+            `Must be a positive integer in the range 1-100000. ` +
+            `Example: --csv-max-rows 500`);
+    }
+}
+//# sourceMappingURL=inputValidation.js.map

package/dist/core/modules/MessageBuilder.js

@@ -22,7 +22,18 @@ function computeTotalContentLength(messages) {
     return total;
 }
 /**
- * Check whether input contains multimodal content (images, files, PDFs, CSVs).
+ * Check whether input contains multimodal content (images, files, PDFs, CSVs,
+ * audio, video). #284: audioFiles/videoFiles were previously ignored here, so a
+ * request carrying only audio or video was misrouted to the text-only path.
+ *
+ * Intentional (round-2 review): routing audio/video through `isMultimodal`
+ * does NOT mean vision is required. `buildMultimodalMessagesArray` folds
+ * `audioFiles`/`videoFiles` into `inp.files` for auto-detection, and
+ * `appendDetectedFileResult` injects their content as plain text markers
+ * (`## Audio File:` / `## Video File:`), not image/vision blocks — see
+ * `test/continuous-test-suite-bugfixes.ts` ("MessageBuilder #284: ...").
+ * "Multimodal" here means "needs the multimodal builder so the payload isn't
+ * dropped", not "needs a vision model".
  */
 function detectMultimodal(opts) {
     const input = opts.input;
@@ -31,10 +42,18 @@ function detectMultimodal(opts) {
     const hasCSVFiles = !!input?.csvFiles?.length;
     const hasPdfFiles = !!input?.pdfFiles?.length;
     const hasFiles = !!input?.files?.length;
+    const hasAudioFiles = !!input?.audioFiles?.length;
+    const hasVideoFiles = !!input?.videoFiles?.length;
     return {
-        isMultimodal: hasImages || hasContent || hasCSVFiles || hasPdfFiles || hasFiles,
+        isMultimodal: hasImages ||
+            hasContent ||
+            hasCSVFiles ||
+            hasPdfFiles ||
+            hasFiles ||
+            hasAudioFiles ||
+            hasVideoFiles,
         hasImages,
-        hasFiles: hasCSVFiles || hasPdfFiles || hasFiles,
+        hasFiles: hasCSVFiles || hasPdfFiles || hasFiles || hasAudioFiles || hasVideoFiles,
     };
 }
 /**
@@ -75,6 +94,12 @@ export class MessageBuilder {
                         content: input?.content,
                         csvFiles: input?.csvFiles,
                         pdfFiles: input?.pdfFiles,
+                        // #284: audioFiles/videoFiles must be forwarded too, or the
+                        // multimodal builder receives an empty payload despite
+                        // detectMultimodal() correctly routing audio/video-only
+                        // requests here.
+                        audioFiles: input?.audioFiles,
+                        videoFiles: input?.videoFiles,
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
@@ -192,6 +217,10 @@ export class MessageBuilder {
                         content: input?.content,
                         csvFiles: input?.csvFiles,
                         pdfFiles: input?.pdfFiles,
+                        // #284: forward audioFiles/videoFiles here too — see the
+                        // matching comment in buildMessages() above.
+                        audioFiles: input?.audioFiles,
+                        videoFiles: input?.videoFiles,
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,

package/dist/lib/core/modules/MessageBuilder.js

@@ -22,7 +22,18 @@ function computeTotalContentLength(messages) {
     return total;
 }
 /**
- * Check whether input contains multimodal content (images, files, PDFs, CSVs).
+ * Check whether input contains multimodal content (images, files, PDFs, CSVs,
+ * audio, video). #284: audioFiles/videoFiles were previously ignored here, so a
+ * request carrying only audio or video was misrouted to the text-only path.
+ *
+ * Intentional (round-2 review): routing audio/video through `isMultimodal`
+ * does NOT mean vision is required. `buildMultimodalMessagesArray` folds
+ * `audioFiles`/`videoFiles` into `inp.files` for auto-detection, and
+ * `appendDetectedFileResult` injects their content as plain text markers
+ * (`## Audio File:` / `## Video File:`), not image/vision blocks — see
+ * `test/continuous-test-suite-bugfixes.ts` ("MessageBuilder #284: ...").
+ * "Multimodal" here means "needs the multimodal builder so the payload isn't
+ * dropped", not "needs a vision model".
  */
 function detectMultimodal(opts) {
     const input = opts.input;
@@ -31,10 +42,18 @@ function detectMultimodal(opts) {
     const hasCSVFiles = !!input?.csvFiles?.length;
     const hasPdfFiles = !!input?.pdfFiles?.length;
     const hasFiles = !!input?.files?.length;
+    const hasAudioFiles = !!input?.audioFiles?.length;
+    const hasVideoFiles = !!input?.videoFiles?.length;
     return {
-        isMultimodal: hasImages || hasContent || hasCSVFiles || hasPdfFiles || hasFiles,
+        isMultimodal: hasImages ||
+            hasContent ||
+            hasCSVFiles ||
+            hasPdfFiles ||
+            hasFiles ||
+            hasAudioFiles ||
+            hasVideoFiles,
         hasImages,
-        hasFiles: hasCSVFiles || hasPdfFiles || hasFiles,
+        hasFiles: hasCSVFiles || hasPdfFiles || hasFiles || hasAudioFiles || hasVideoFiles,
     };
 }
 /**
@@ -75,6 +94,12 @@ export class MessageBuilder {
                         content: input?.content,
                         csvFiles: input?.csvFiles,
                         pdfFiles: input?.pdfFiles,
+                        // #284: audioFiles/videoFiles must be forwarded too, or the
+                        // multimodal builder receives an empty payload despite
+                        // detectMultimodal() correctly routing audio/video-only
+                        // requests here.
+                        audioFiles: input?.audioFiles,
+                        videoFiles: input?.videoFiles,
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
@@ -192,6 +217,10 @@ export class MessageBuilder {
                         content: input?.content,
                         csvFiles: input?.csvFiles,
                         pdfFiles: input?.pdfFiles,
+                        // #284: forward audioFiles/videoFiles here too — see the
+                        // matching comment in buildMessages() above.
+                        audioFiles: input?.audioFiles,
+                        videoFiles: input?.videoFiles,
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,

package/dist/lib/types/generate.d.ts

@@ -53,6 +53,7 @@ export type GenerateOptions = {
         images?: Array<Buffer | string | ImageWithAltText>;
         csvFiles?: Array<Buffer | string>;
         pdfFiles?: Array<Buffer | string>;
+        audioFiles?: Array<Buffer | string>;
         videoFiles?: Array<Buffer | string>;
         files?: Array<Buffer | string | FileWithMetadata>;
         content?: Content[];

package/dist/lib/types/multimodal.d.ts

@@ -419,15 +419,46 @@ export type MultimodalInput = {
     segments?: DirectorSegment[];
 };
 /**
- * Content format for multimodal messages (used internally)
- * Compatible with Vercel AI SDK message format
+ * Content format for multimodal messages (used internally).
+ *
+ * #325: the loose `[key: string]: unknown` index signature has been replaced
+ * with the concrete fields the codebase actually reads/writes across the
+ * text / image / file / tool-call / tool-result shapes. This keeps the broad
+ * structural compatibility the internal pipeline relies on (a single object
+ * type, not a strict discriminated union that would force narrowing at every
+ * consumer) while removing the "any key is allowed" hole that let typos and
+ * unrelated keys through unchecked.
  */
 export type MessageContent = {
     type: string;
+    /** Text content (`type: "text"`). */
     text?: string;
+    /** Base64 / data-URI image (`type: "image"`). */
     image?: string;
+    /** MIME type for image/file parts. */
     mimeType?: string;
-    [key: string]: unknown;
+    /** Raw file bytes or base64 (`type: "file"`/document parts). */
+    data?: string | Buffer;
+    /** File name for document/file parts. */
+    name?: string;
+    /** File name (alias used by some file parts). */
+    filename?: string;
+    /** Tool-call identifier (`type: "tool-call"`/`"tool-result"`). */
+    toolCallId?: string;
+    /** Tool name (`type: "tool-call"`/`"tool-result"`). */
+    toolName?: string;
+    /** Tool-call arguments (`type: "tool-call"`). */
+    args?: Record<string, unknown>;
+    /** Tool-result payload (`type: "tool-result"`). */
+    result?: unknown;
+    /** Whether a tool-result represents an error (`type: "tool-result"`). */
+    isError?: boolean;
+    /**
+     * Provider-specific per-block options (e.g. Anthropic cache_control).
+     * Read as `item.providerOptions` when converting `MessageContent[]` to
+     * `ModelMessage[]` in `MessageBuilder.ts`.
+     */
+    providerOptions?: Record<string, unknown>;
 };
 /**
  * Extended chat message for multimodal support (internal use)

package/dist/lib/types/stream.d.ts

@@ -193,6 +193,7 @@ export type StreamOptions = {
         images?: Array<Buffer | string | ImageWithAltText>;
         csvFiles?: Array<Buffer | string>;
         pdfFiles?: Array<Buffer | string>;
+        audioFiles?: Array<Buffer | string>;
         videoFiles?: Array<Buffer | string>;
         files?: Array<Buffer | string | FileWithMetadata>;
         content?: Content[];

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

@@ -35,6 +35,9 @@ export declare const ERROR_CODES: {
     readonly IMAGE_TOO_SMALL: "IMAGE_TOO_SMALL";
     readonly INVALID_IMAGE_FORMAT: "INVALID_IMAGE_FORMAT";
     readonly INVALID_IMAGE_SIZE: "INVALID_IMAGE_SIZE";
+    readonly IMAGE_BUFFER_INVALID: "IMAGE_BUFFER_INVALID";
+    readonly FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED";
+    readonly CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED";
     readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
     readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
     readonly RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT";
@@ -216,6 +219,13 @@ export declare class ErrorFactory {
      * Create an invalid image format error
      */
     static invalidImageFormat(): NeuroLinkError;
+    /**
+     * Create an image buffer validation error: empty, undersized, or a
+     * truncated buffer detected by `ImageProcessor.validateBufferNotEmpty()`.
+     * Takes the fully-formed message so call sites keep their specific
+     * byte-count detail instead of a fixed generic message.
+     */
+    static imageBufferInvalid(message: string): NeuroLinkError;
     /**
      * Create a rate limiter queue full error
      */
@@ -287,6 +297,18 @@ export declare class ErrorFactory {
      * generic `Error` instances.
      */
     static proxyWorkerLifecycle(message: string, context?: Record<string, unknown>): NeuroLinkError;
+    /**
+     * Create a generic file-processing-failed error (e.g. an unrecognized or
+     * corrupt file in `processUnifiedFilesArray`). Preserves the original error
+     * as `originalError` (stack + message copied onto the new error's context).
+     */
+    static fileProcessingFailed(filename: string, originalError: Error): NeuroLinkError;
+    /**
+     * Create a generic CSV-processing-failed error (explicit `csvFiles` path,
+     * distinct from `fileProcessingFailed` so callers can classify CSV-specific
+     * failures separately). Preserves the original error as `originalError`.
+     */
+    static csvProcessingFailed(filename: string, originalError: Error): NeuroLinkError;
 }
 /**
  * Timeout wrapper for async operations