@juspay/neurolink 9.95.0 → 9.95.2

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

@@ -22,6 +22,16 @@ export declare class CLICommandFactory {
     private static processCliImages;
     private static processCliCSVFiles;
     private static processCliPDFFiles;
+    /**
+     * Resolve the PDF decryption password, preferring the NEUROLINK_PDF_PASSWORD
+     * env var over the `--pdf-password` flag. A plaintext CLI flag leaks into
+     * shell history, `ps`/process listings, and CI logs — the env var avoids
+     * that, matching the project's existing "credentials via env vars, not
+     * flags" stance for the loop session. The flag stays supported (dropping it
+     * would be a breaking CLI change), but using it prints a one-line stderr
+     * warning recommending the env var instead.
+     */
+    private static resolvePdfPassword;
     private static processCliFiles;
     private static processCliVideoFiles;
     private static processOptions;

package/dist/cli/factories/commandFactory.js

@@ -24,7 +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 { validateCliInputFiles, validateCsvMaxRows, validatePromptsFilePath, } from "../utils/inputValidation.js";
 import { animatedWrite } from "../utils/typewriter.js";
 import { createStreamAbortHandler } from "../utils/abortHandler.js";
 import { formatVideoFileSize, getVideoMetadataSummary, saveVideoToFile, } from "../utils/videoFileUtils.js";
@@ -156,6 +156,12 @@ export class CLICommandFactory {
             type: "string",
             description: "Add PDF file for analysis (can be used multiple times)",
         },
+        "pdf-password": {
+            type: "string",
+            description: "Password for an encrypted PDF (used on the image-conversion path). " +
+                "Visible in shell history/process listings — prefer the " +
+                "NEUROLINK_PDF_PASSWORD env var instead.",
+        },
         video: {
             type: "string",
             description: "Add video file for analysis (can be used multiple times) (MP4, WebM, MOV, AVI, MKV)",
@@ -742,11 +748,18 @@ export class CLICommandFactory {
             alias: "skills-dir",
         },
     };
-    // Helper method to build options for commands
-    static buildOptions(yargs, additionalOptions = {}) {
+    // Helper method to build options for commands. `excludeOptions` drops
+    // common flags from registration entirely (not just from validation) —
+    // #1191 round-5: batch uses this to omit `commonOptions.file` so `--file`
+    // isn't a recognized flag at all, since it would collide with the
+    // `<file>` positional (the prompts list).
+    static buildOptions(yargs, additionalOptions = {}, excludeOptions = []) {
+        const baseOptions = excludeOptions.length === 0
+            ? CLICommandFactory.commonOptions
+            : Object.fromEntries(Object.entries(CLICommandFactory.commonOptions).filter(([key]) => !excludeOptions.includes(key)));
         return (yargs
             .options({
-            ...CLICommandFactory.commonOptions,
+            ...baseOptions,
             ...additionalOptions,
         })
             // NEW9: implies relationships so users who pass --stt-provider or
@@ -786,6 +799,24 @@ export class CLICommandFactory {
         // URLs are preserved as-is by resolveFilePaths
         return resolveFilePaths(paths);
     }
+    /**
+     * Resolve the PDF decryption password, preferring the NEUROLINK_PDF_PASSWORD
+     * env var over the `--pdf-password` flag. A plaintext CLI flag leaks into
+     * shell history, `ps`/process listings, and CI logs — the env var avoids
+     * that, matching the project's existing "credentials via env vars, not
+     * flags" stance for the loop session. The flag stays supported (dropping it
+     * would be a breaking CLI change), but using it prints a one-line stderr
+     * warning recommending the env var instead.
+     */
+    static resolvePdfPassword(argv) {
+        const flagValue = argv.pdfPassword;
+        const envValue = process.env.NEUROLINK_PDF_PASSWORD;
+        if (flagValue) {
+            process.stderr.write(chalk.yellow("⚠️  --pdf-password is visible in shell history and process listings. " +
+                "Prefer the NEUROLINK_PDF_PASSWORD environment variable instead.\n"));
+        }
+        return flagValue || envValue;
+    }
     // Helper method to process CLI files with auto-detection
     static processCliFiles(files) {
         if (!files) {
@@ -1543,11 +1574,19 @@ export class CLICommandFactory {
      */
     static createBatchCommand() {
         return {
-            command: "batch <file>",
+            // #1191 round-5: the positional is named `promptsFile`, not `file` —
+            // yargs implicitly accepts `--<positionalName>` as a flag alias for
+            // any positional regardless of whether it's separately registered via
+            // `.options()`, so a positional literally named `file` would let
+            // `--file` silently pass strictOptions() even after removing
+            // `commonOptions.file` below. Renaming the key (invocation syntax is
+            // unaffected — it's still just `neurolink batch prompts.txt`) is what
+            // actually makes `--file` an unknown argument.
+            command: "batch <promptsFile>",
             describe: "Process multiple prompts from a file",
             builder: (yargs) => {
                 return CLICommandFactory.buildOptions(yargs
-                    .positional("file", {
+                    .positional("promptsFile", {
                     type: "string",
                     description: "File with prompts (one per line)",
                     demandOption: true,
@@ -1555,7 +1594,11 @@ export class CLICommandFactory {
                     .example("$0 batch prompts.txt", "Process prompts from file")
                     .example("$0 batch questions.txt --format json", "Export results as JSON")
                     .example("$0 batch tasks.txt -p vertex --delay 2000", "Use Vertex AI with 2s delay")
-                    .example("$0 batch batch.txt --output results.json", "Save results to file"));
+                    .example("$0 batch batch.txt --output results.json", "Save results to file"), {}, 
+                // `--file` is not a batch flag — the positional above is the
+                // prompts-list path. Omit it from registration so it's rejected
+                // as unknown rather than silently accepted then ignored.
+                ["file"]);
             },
             handler: async (argv) => await CLICommandFactory.executeBatch(argv),
         };
@@ -2630,6 +2673,9 @@ export class CLICommandFactory {
             const inputAudioFormat = inferAudioFormatFromPath(inputAudioPath);
             const runGenerate = () => sdk.generate({
                 input: generateInput,
+                pdfOptions: {
+                    password: CLICommandFactory.resolvePdfPassword(argv),
+                },
                 csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
                 videoOptions: {
                     frames: argv.videoFrames,
@@ -2882,6 +2928,9 @@ export class CLICommandFactory {
                 ...(videoFiles && { videoFiles }),
                 ...(files && { files }),
             },
+            pdfOptions: {
+                password: CLICommandFactory.resolvePdfPassword(argv),
+            },
             csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
             videoOptions: {
                 frames: argv.videoFrames,
@@ -3349,13 +3398,30 @@ export class CLICommandFactory {
         CLICommandFactory.validateAnthropicSubscriptionOptions(options);
         const spinner = options.quiet ? null : ora().start();
         try {
-            if (!argv.file) {
+            if (!argv.promptsFile) {
                 throw new Error("No file specified");
             }
-            if (!fs.existsSync(argv.file)) {
-                throw new Error(`File not found: ${argv.file}`);
-            }
-            const buffer = fs.readFileSync(argv.file);
+            // #291/round-4 #1191: validate multimodal flags and resolve their
+            // paths *before* the prompts file is read/parsed below, mirroring
+            // generate/stream (which validate all inputs before any processing).
+            // Previously this ran after `fs.readFileSync(resolvedPromptsPath)`,
+            // so a large prompts file paired with an invalid --image path paid
+            // the read/parse cost before the flag error ever surfaced. `--file`
+            // (the common auto-detect flag) isn't registered on batch at all —
+            // see createBatchCommand — so `argv.file` can never be set here; no
+            // exclusion needed to protect the (differently-named) positional.
+            validateCliInputFiles(argv);
+            const batchImages = CLICommandFactory.processCliImages(argv.image);
+            const batchCsvFiles = CLICommandFactory.processCliCSVFiles(argv.csv);
+            const batchPdfFiles = CLICommandFactory.processCliPDFFiles(argv.pdf);
+            const batchVideoFiles = CLICommandFactory.processCliVideoFiles(argv.video);
+            // #291: route the prompts-list positional through the same friendly
+            // aggregated-error path as the multimodal flags above (not found /
+            // unreadable / directory / malformed file:// URL), instead of a raw
+            // existsSync+readFileSync that throws an unfriendly EISDIR when
+            // pointed at a directory.
+            const resolvedPromptsPath = validatePromptsFilePath(argv.promptsFile);
+            const buffer = fs.readFileSync(resolvedPromptsPath);
             const prompts = buffer
                 .toString("utf8")
                 .split("\n")
@@ -3390,6 +3456,19 @@ export class CLICommandFactory {
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
             const enhancedOptions = { ...options, ...sessionVariables };
             const sessionId = globalSession.getCurrentSessionId();
+            // batchImages/batchCsvFiles/batchPdfFiles/batchVideoFiles were already
+            // validated and resolved above, before the prompts file was read.
+            if (batchImages?.length ||
+                batchCsvFiles?.length ||
+                batchPdfFiles?.length ||
+                batchVideoFiles?.length) {
+                // Pause the spinner so the notice isn't swallowed by its re-renders.
+                // Safety-relevant, so always visible (not gated behind --quiet) and
+                // written to stderr so `--format json` output on stdout stays parseable.
+                spinner?.stop();
+                logger.alwaysStderr(chalk.yellow("⚠️  Multimodal files (--image/--csv/--pdf/--video) are attached to ALL prompts in this batch."));
+                spinner?.start();
+            }
             for (let i = 0; i < prompts.length; i++) {
                 if (spinner) {
                     spinner.text = `Processing ${i + 1}/${prompts.length}: ${prompts[i].substring(0, 30)}...`;
@@ -3425,7 +3504,33 @@ export class CLICommandFactory {
                         ? { ...contextMetadata, sessionId }
                         : contextMetadata;
                     const runBatchGenerate = () => sdk.generate({
-                        input: { text: inputText },
+                        input: {
+                            text: inputText,
+                            ...(batchImages?.length && { images: batchImages }),
+                            ...(batchCsvFiles?.length && { csvFiles: batchCsvFiles }),
+                            ...(batchPdfFiles?.length && { pdfFiles: batchPdfFiles }),
+                            ...(batchVideoFiles?.length && {
+                                videoFiles: batchVideoFiles,
+                            }),
+                        },
+                        // Only construct these when the corresponding files are
+                        // actually attached — batch has no CSV/video mode to opt into,
+                        // unlike generate/stream, so an empty options object here is
+                        // pure noise on every prompt of every batch run.
+                        ...(batchCsvFiles?.length && {
+                            csvOptions: {
+                                maxRows: argv.csvMaxRows,
+                                formatStyle: argv.csvFormat,
+                            },
+                        }),
+                        ...(batchVideoFiles?.length && {
+                            videoOptions: {
+                                frames: argv.videoFrames,
+                                quality: argv.videoQuality,
+                                format: argv.videoFormat,
+                                transcribeAudio: argv.transcribeAudio,
+                            },
+                        }),
                         provider: enhancedOptions.provider,
                         model: enhancedOptions.model,
                         temperature: enhancedOptions.temperature,

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

@@ -4,4 +4,4 @@ import type { OptionSchema, TextGenerationOptions } from "../../lib/types/index.
  * 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" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation">, OptionSchema>;
+export declare const textGenerationOptionsSchema: Record<keyof Omit<TextGenerationOptions, "prompt" | "input" | "schema" | "tools" | "context" | "conversationHistory" | "conversationMessages" | "conversationMemoryConfig" | "originalPrompt" | "middleware" | "expectedOutcome" | "evaluationCriteria" | "region" | "csvOptions" | "pdfOptions" | "tts" | "stt" | "thinkingConfig" | "requestId" | "fileRegistry" | "abortSignal" | "toolFilter" | "excludeTools" | "toolChoice" | "prepareStep" | "credentials" | "onFinish" | "onError" | "processors" | "piiDetection" | "responseValidation" | "inputValidation">, OptionSchema>;

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

@@ -1,12 +1,13 @@
 /**
  * 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.
+ * Validates multimodal file flags (--image/--csv/--pdf/--video/--file), the
+ * batch `<promptsFile>` positional, 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
@@ -24,11 +25,23 @@ export declare const CLI_SOFT_LIMITS_MB: {
 };
 /**
  * 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).
+ * starts: every local path (including `file://` URLs) must exist, must not
+ * be a directory, and — for the flags with a soft limit — triggers a size
+ * warning above the threshold. Genuine http(s)/data: URLs skip both
+ * existence and size checks (#319).
  */
 export declare function validateCliInputFiles(argv: Record<string, unknown>): void;
+/**
+ * #291: validate the batch `<promptsFile>` positional through the same
+ * aggregated-error-friendly path as the multimodal flags above (not found /
+ * unreadable / directory / malformed `file://` URL), instead of a raw
+ * existsSync+readFileSync that throws an unfriendly EISDIR when pointed at
+ * a directory. The `<file>` label (rather than `--file`) keeps the message
+ * from being confused with the `--file` flag, which batch doesn't register
+ * at all (see `createBatchCommand`). Returns the resolved local path for
+ * the caller to read.
+ */
+export declare function validatePromptsFilePath(rawPath: string): string;
 /**
  * #310: validate --csv-max-rows is a positive integer in the range
  * 1-100000, matching the documented option range (the value previously

package/dist/cli/utils/inputValidation.js

@@ -1,17 +1,20 @@
 /**
  * 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.
+ * Validates multimodal file flags (--image/--csv/--pdf/--video/--file), the
+ * batch `<promptsFile>` positional, 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 { fileURLToPath } from "node:url";
 import chalk from "chalk";
 import { logger } from "../../lib/utils/logger.js";
-import { resolveFilePaths } from "./pathResolver.js";
+import { redactUrlForError } from "../../lib/utils/logSanitize.js";
+import { resolveFilePath } from "./pathResolver.js";
 /**
  * Soft (warn-only) size thresholds for CLI multimodal flags. Intentionally
  * defined here rather than reusing `lib/processors/config/sizeLimits.ts`'s
@@ -26,18 +29,126 @@ export const CLI_SOFT_LIMITS_MB = {
     PDF_MAX_MB: 100,
     VIDEO_MAX_MB: 500,
 };
+// `file://` is intentionally excluded here: it addresses a local path, so it
+// must still go through directory/missing-path validation below (via
+// tryResolveFileUrl in validateSingleLocalPath). Only genuine remote/inline
+// references (http(s), data URIs) skip validation entirely (#319).
 function isNonLocalFileReference(filePath) {
     const lower = filePath.toLowerCase();
     return (lower.startsWith("http://") ||
         lower.startsWith("https://") ||
-        lower.startsWith("file://") ||
         lower.startsWith("data:"));
 }
+// #291: a `file://` URL still points at something on disk, so validation
+// needs the real filesystem path. Returns undefined (instead of throwing)
+// for a malformed URL so the caller can report a friendly error.
+function tryResolveFileUrl(filePath) {
+    if (!filePath.toLowerCase().startsWith("file://")) {
+        return filePath;
+    }
+    try {
+        return fileURLToPath(filePath);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Shared aggregated-error format for any invalid local file path (missing,
+ * unreadable, a directory, or a malformed `file://` URL). Used by both the
+ * flag-based loop in `validateCliInputFiles` and the batch `<promptsFile>`
+ * positional check in `validatePromptsFilePath`, so every caller gets the
+ * same clear error + troubleshooting hints instead of a raw exception.
+ */
+function buildInvalidFileError(errors) {
+    return new Error("❌ One or more input files are invalid:\n" +
+        `${errors.join("\n")}\n` +
+        "💡 Troubleshooting:\n" +
+        "  • Check the path is correct and relative to your current directory, or pass an absolute path / URL.\n" +
+        `  • Check your working directory (${process.cwd()}).\n` +
+        "  • For remote resources, prefix the value with http:// or https://.\n" +
+        "  • If you pointed at a folder, point at the file inside it instead.");
+}
+/**
+ * Validate a single raw path/URL value for `option`, pushing a friendly
+ * message onto `errors` instead of letting fs calls throw a raw exception
+ * (ENOENT, EACCES/EPERM TOCTOU, a directory, or a malformed `file://` URL).
+ * Returns the resolved local filesystem path on success (or the original
+ * value unchanged for a skipped http(s)/data: reference), and `undefined`
+ * when an error was pushed.
+ *
+ * `rawPath` is redacted via `redactUrlForError` before ever being
+ * interpolated into a message — a `file://` value can carry a sensitive
+ * query string, fragment, or embedded `user:pass@` credentials that must
+ * never be echoed back verbatim. This is a no-op for ordinary filesystem
+ * paths (they aren't parseable as a URL, so the redaction fallback simply
+ * returns them unchanged).
+ */
+function validateSingleLocalPath(option, rawPath, errors, warnAtMB) {
+    const resolvedPath = resolveFilePath(rawPath);
+    if (isNonLocalFileReference(resolvedPath)) {
+        // URLs / data: refs skip both existence and size checks (#319).
+        return resolvedPath;
+    }
+    const safeRawPath = redactUrlForError(rawPath);
+    // #291: `file://` URLs are local paths in disguise — validate the decoded
+    // filesystem path so a directory or missing path is still caught here
+    // instead of failing cryptically deep in processing.
+    const pathToValidate = tryResolveFileUrl(resolvedPath);
+    if (pathToValidate === undefined) {
+        errors.push(`${option} is not a valid file:// URL: ${safeRawPath}`);
+        return undefined;
+    }
+    const safeResolvedPath = redactUrlForError(pathToValidate);
+    // 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(pathToValidate);
+    }
+    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") {
+            errors.push(`${option} path not found: ${safeRawPath} (resolved to ${safeResolvedPath})`);
+        }
+        else {
+            const reason = err instanceof Error ? err.message : String(err);
+            errors.push(`${option} path could not be accessed: ${safeRawPath} (resolved to ${safeResolvedPath}) — ` +
+                `${code ? `${code}: ` : ""}${reason}`);
+        }
+        return undefined;
+    }
+    // #288: reject a directory before it fails cryptically deep in processing
+    // (readFileSync on a dir throws a raw EISDIR).
+    if (stat.isDirectory()) {
+        errors.push(`${option} path is a directory, not a file: ${safeRawPath} (resolved to ${safeResolvedPath})`);
+        return undefined;
+    }
+    // #319: warn (not error) when a local multimodal file is unusually large
+    // so the user isn't surprised by slow processing / token blowups. Safety-
+    // relevant, so always visible (not gated behind --quiet) and written to
+    // stderr — never stdout — so `--format json` output stays parseable.
+    if (warnAtMB !== undefined) {
+        const sizeMB = stat.size / (1024 * 1024);
+        if (sizeMB > warnAtMB) {
+            logger.alwaysStderr(chalk.yellow(`⚠️  ${option} file ${safeRawPath} is ${sizeMB.toFixed(1)}MB ` +
+                `(above the ${warnAtMB}MB soft limit) — processing may be slow ` +
+                `or exceed provider token/size limits.`));
+        }
+    }
+    return pathToValidate;
+}
 /**
  * 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).
+ * starts: every local path (including `file://` URLs) must exist, must not
+ * be a directory, and — for the flags with a soft limit — triggers a size
+ * warning above the threshold. Genuine http(s)/data: URLs skip both
+ * existence and size checks (#319).
  */
 export function validateCliInputFiles(argv) {
     const fileArgs = [
@@ -63,64 +174,39 @@ export function validateCliInputFiles(argv) {
         },
         { option: "--file", value: argv.file },
     ];
-    const missingPaths = [];
+    const errors = [];
     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.`));
-                }
-            }
+        for (const rawPath of rawPaths) {
+            validateSingleLocalPath(option, rawPath, errors, warnAtMB);
         }
     }
-    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.");
+    if (errors.length > 0) {
+        throw buildInvalidFileError(errors);
+    }
+}
+/**
+ * #291: validate the batch `<promptsFile>` positional through the same
+ * aggregated-error-friendly path as the multimodal flags above (not found /
+ * unreadable / directory / malformed `file://` URL), instead of a raw
+ * existsSync+readFileSync that throws an unfriendly EISDIR when pointed at
+ * a directory. The `<file>` label (rather than `--file`) keeps the message
+ * from being confused with the `--file` flag, which batch doesn't register
+ * at all (see `createBatchCommand`). Returns the resolved local path for
+ * the caller to read.
+ */
+export function validatePromptsFilePath(rawPath) {
+    const errors = [];
+    const resolved = validateSingleLocalPath("<file>", rawPath, errors);
+    if (errors.length > 0) {
+        throw buildInvalidFileError(errors);
     }
+    // `errors` is empty here, so `validateSingleLocalPath` did not return
+    // undefined.
+    return resolved;
 }
 /**
  * #310: validate --csv-max-rows is a positive integer in the range

package/dist/core/baseProvider.js

@@ -420,6 +420,7 @@ export class BaseProvider {
                 toolUsageContext: options.toolUsageContext,
                 context: options.context,
                 csvOptions: options.csvOptions,
+                pdfOptions: options.pdfOptions,
                 // 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/constants.d.ts

@@ -122,6 +122,8 @@ export declare const PDF_LIMITS: {
     MAX_SIZE_MB: number;
     DEFAULT_MAX_PAGES: number;
     MAX_SCALE: number;
+    DEFAULT_MAX_CANVAS_PIXELS: number;
+    MIN_EFFECTIVE_SCALE: number;
 };
 export declare const SYSTEM_LIMITS: {
     MAX_PROMPT_LENGTH: number;

package/dist/core/constants.js

@@ -220,6 +220,15 @@ export const PDF_LIMITS = {
     // Upper bound for the render scale factor. Above this, a single page can
     // allocate hundreds of MB; scale <= 0 produces a degenerate viewport.
     MAX_SCALE: 10,
+    // Default per-page pixel ceiling for image conversion (#260). 16.7M px ×
+    // 4 bytes RGBA ≈ 64 MB per page — safely bounded. A larger page is
+    // uniformly downscaled to stay under this instead of allocating gigabytes.
+    DEFAULT_MAX_CANVAS_PIXELS: 16_777_216,
+    // Floor for the downscaled render scale (#260 follow-up). A crafted/malformed
+    // MediaBox can drive the estimated pixel count toward Infinity, which would
+    // otherwise collapse `effectiveScale` to 0 and hand `pdf-to-img` a degenerate
+    // viewport. Never let the downscale branch go below this.
+    MIN_EFFECTIVE_SCALE: 0.1,
 };
 // Performance and System Limits
 export const SYSTEM_LIMITS = {

package/dist/core/modules/MessageBuilder.js

@@ -103,6 +103,7 @@ export class MessageBuilder {
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
+                    pdfOptions: options.pdfOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,
@@ -224,6 +225,7 @@ export class MessageBuilder {
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
+                    pdfOptions: options.pdfOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,

package/dist/lib/core/baseProvider.js

@@ -420,6 +420,7 @@ export class BaseProvider {
                 toolUsageContext: options.toolUsageContext,
                 context: options.context,
                 csvOptions: options.csvOptions,
+                pdfOptions: options.pdfOptions,
                 // 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/lib/core/constants.d.ts

@@ -122,6 +122,8 @@ export declare const PDF_LIMITS: {
     MAX_SIZE_MB: number;
     DEFAULT_MAX_PAGES: number;
     MAX_SCALE: number;
+    DEFAULT_MAX_CANVAS_PIXELS: number;
+    MIN_EFFECTIVE_SCALE: number;
 };
 export declare const SYSTEM_LIMITS: {
     MAX_PROMPT_LENGTH: number;

package/dist/lib/core/constants.js

@@ -220,6 +220,15 @@ export const PDF_LIMITS = {
     // Upper bound for the render scale factor. Above this, a single page can
     // allocate hundreds of MB; scale <= 0 produces a degenerate viewport.
     MAX_SCALE: 10,
+    // Default per-page pixel ceiling for image conversion (#260). 16.7M px ×
+    // 4 bytes RGBA ≈ 64 MB per page — safely bounded. A larger page is
+    // uniformly downscaled to stay under this instead of allocating gigabytes.
+    DEFAULT_MAX_CANVAS_PIXELS: 16_777_216,
+    // Floor for the downscaled render scale (#260 follow-up). A crafted/malformed
+    // MediaBox can drive the estimated pixel count toward Infinity, which would
+    // otherwise collapse `effectiveScale` to 0 and hand `pdf-to-img` a degenerate
+    // viewport. Never let the downscale branch go below this.
+    MIN_EFFECTIVE_SCALE: 0.1,
 };
 // Performance and System Limits
 export const SYSTEM_LIMITS = {

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

@@ -103,6 +103,7 @@ export class MessageBuilder {
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
+                    pdfOptions: options.pdfOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,
@@ -224,6 +225,7 @@ export class MessageBuilder {
                         files: input?.files,
                     },
                     csvOptions: options.csvOptions,
+                    pdfOptions: options.pdfOptions,
                     provider: options.provider,
                     model: options.model,
                     temperature: options.temperature,