@juspay/neurolink 9.95.1 → 9.95.3

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

@@ -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)",
@@ -793,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) {
@@ -2649,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,
@@ -2901,6 +2928,9 @@ export class CLICommandFactory {
                 ...(videoFiles && { videoFiles }),
                 ...(files && { files }),
             },
+            pdfOptions: {
+                password: CLICommandFactory.resolvePdfPassword(argv),
+            },
             csvOptions: CLICommandFactory.buildCsvOptionsFromArgv(argv),
             videoOptions: {
                 frames: argv.videoFrames,

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/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,11 @@ export declare const PDF_LIMITS: {
     MAX_SIZE_MB: number;
     DEFAULT_MAX_PAGES: number;
     MAX_SCALE: number;
+    MIN_SCALE: number;
+    DEFAULT_SCALE: number;
+    PAGE_COUNT_TIMEOUT_MS: 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,25 @@ 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,
+    // Lower bound for the render scale factor (#297). Below this the render is
+    // effectively unreadable; enforcing it makes the documented 0.1–10 range real
+    // (previously only scale <= 0 was rejected).
+    MIN_SCALE: 0.1,
+    // Default render scale (#297). Lowered from 2 → 1.5 to roughly halve the
+    // per-page canvas memory while staying legible for OCR/vision.
+    DEFAULT_SCALE: 1.5,
+    // Timeout (ms) for the accurate pdf-parse page-count probe (#287); on timeout
+    // the processor falls back to the regex estimate rather than blocking.
+    PAGE_COUNT_TIMEOUT_MS: 5000,
+    // 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,11 @@ export declare const PDF_LIMITS: {
     MAX_SIZE_MB: number;
     DEFAULT_MAX_PAGES: number;
     MAX_SCALE: number;
+    MIN_SCALE: number;
+    DEFAULT_SCALE: number;
+    PAGE_COUNT_TIMEOUT_MS: 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,25 @@ 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,
+    // Lower bound for the render scale factor (#297). Below this the render is
+    // effectively unreadable; enforcing it makes the documented 0.1–10 range real
+    // (previously only scale <= 0 was rejected).
+    MIN_SCALE: 0.1,
+    // Default render scale (#297). Lowered from 2 → 1.5 to roughly halve the
+    // per-page canvas memory while staying legible for OCR/vision.
+    DEFAULT_SCALE: 1.5,
+    // Timeout (ms) for the accurate pdf-parse page-count probe (#287); on timeout
+    // the processor falls back to the regex estimate rather than blocking.
+    PAGE_COUNT_TIMEOUT_MS: 5000,
+    // 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,

package/dist/lib/neurolink.js

@@ -3899,11 +3899,15 @@ Current user's request: ${currentInput}`;
             evaluationDomain: options.evaluationDomain,
             toolUsageContext: options.toolUsageContext,
             input: options.input,
-            // CSV processing options must survive the reconstruction into
-            // TextGenerationOptions — the message builder reads them (encoding,
-            // formatting, sanitization, parse timeout). Omitting them silently
-            // dropped every csvOptions field (incl. the CLI --csv-* flags).
+            // Multimodal file-processing options must survive the reconstruction
+            // into TextGenerationOptions — the message builder reads them downstream
+            // (csv encoding/formatting/sanitization/parse timeout, PDF
+            // password/decryption #258). Omitting them here silently dropped e.g.
+            // every csvOptions field (incl. the CLI --csv-* flags) or
+            // pdfOptions.password so the CLI --pdf-password / SDK pdfOptions never
+            // reached convertToImages.
             csvOptions: options.csvOptions,
+            pdfOptions: options.pdfOptions,
             region: options.region,
             tts: options.tts,
             stt: options.stt,

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

@@ -95,6 +95,8 @@ export type FileProcessingResult = {
         estimatedPages?: number | null;
         provider?: string;
         apiType?: PDFAPIType;
+        /** Provider's citations requirement for visual PDF analysis (#349). */
+        requiresCitations?: boolean | "auto";
         officeFormat?: OfficeDocumentType;
         pageCount?: number;
         slideCount?: number;
@@ -210,6 +212,14 @@ export type PDFProviderConfig = {
     maxSizeMB: number;
     maxPages: number;
     supportsNative: boolean;
+    /**
+     * Whether this provider needs source citations enabled for visual PDF
+     * analysis (#349). `"auto"` = enable when the request requires visual
+     * grounding (currently Bedrock's Converse document blocks); `false` = the
+     * provider handles PDFs without an explicit citations flag. Surfaced on
+     * `FileProcessingResult.metadata.requiresCitations` so downstream provider
+     * adapters can act on it instead of the value being dead config.
+     */
     requiresCitations: boolean | "auto";
     apiType: PDFAPIType;
 };
@@ -226,6 +236,8 @@ export type PDFProcessorOptions = {
      * Set to false to bypass limit enforcement (logs warning instead)
      */
     enforceLimits?: boolean;
+    /** Password for an encrypted PDF (used on the image-conversion path) (#258). */
+    password?: string;
 };
 /**
  * Audio provider configuration for transcription services
@@ -395,10 +407,40 @@ export type PDFImageConversionOptions = {
     maxPages?: number;
     /** Output format (default: png). Only PNG is currently implemented by PDFProcessor. */
     format?: "png";
+    /**
+     * Per-page pixel ceiling (#260). Any page whose width×height×scale² would
+     * exceed this is uniformly downscaled to stay under it, preventing a huge
+     * page from allocating gigabytes of canvas. Default: PDF_LIMITS.DEFAULT_MAX_CANVAS_PIXELS.
+     */
+    maxCanvasPixels?: number;
+    /** Password for an encrypted PDF (passed to the underlying renderer) (#258). */
+    password?: string;
+    /** Per-page progress callback invoked as each page is rendered (#302). */
+    onProgress?: (progress: PDFImageConversionProgress) => void | Promise<void>;
+};
+/** Progress reported per page during streaming conversion (#302). */
+export type PDFImageConversionProgress = {
+    /** Number of pages successfully converted so far. */
+    pagesConverted: number;
+    /** Total pages in the document (known up-front from the renderer). */
+    totalPages: number;
+    /** Elapsed time since conversion started, in milliseconds. */
+    elapsedMs: number;
+};
+/** A single streamed page result (#302). `error` is set when that page failed. */
+export type PDFImagePage = {
+    /** 1-based page index. */
+    pageIndex: number;
+    /** Base64-encoded PNG for the page (empty string when `error` is set). */
+    image: string;
+    /** Byte size of the rendered PNG (0 when `error` is set). */
+    imageSizeBytes: number;
+    /** Populated when this page failed to render (#294). */
+    error?: string;
 };
 /** Result of PDF to image conversion. */
 export type PDFImageConversionResult = {
-    /** Array of base64-encoded PNG images (one per page) */
+    /** Array of base64-encoded PNG images (one per successfully converted page) */
     images: string[];
     /** Number of pages converted */
     pageCount: number;
@@ -406,6 +448,11 @@ export type PDFImageConversionResult = {
     conversionTimeMs: number;
     /** Any warnings during conversion */
     warnings?: string[];
+    /** Per-page failures — present only when some pages failed to render (#294). */
+    errors?: Array<{
+        page: number;
+        error: string;
+    }>;
 };
 /** Options for filename sanitization. */
 export type SanitizeFileNameOptions = {

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

@@ -125,6 +125,13 @@ export type GenerateOptions = {
         music?: MusicOptions;
     };
     csvOptions?: CSVProcessorOptions;
+    /** PDF processing options (#258). */
+    pdfOptions?: {
+        /** Password for an encrypted PDF (image-conversion fallback path). */
+        password?: string;
+        /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
+        maxCanvasPixels?: number;
+    };
     videoOptions?: {
         frames?: number;
         quality?: number;
@@ -1131,6 +1138,13 @@ export type TextGenerationOptions = {
     expectedOutcome?: string;
     evaluationCriteria?: string[];
     csvOptions?: CSVProcessorOptions;
+    /** PDF processing options (#258). */
+    pdfOptions?: {
+        /** Password for an encrypted PDF (image-conversion fallback path). */
+        password?: string;
+        /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
+        maxCanvasPixels?: number;
+    };
     enableSummarization?: boolean;
     /**
      * Skip injecting tool schemas into the system prompt.

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

@@ -207,6 +207,13 @@ export type StreamOptions = {
         };
     };
     csvOptions?: CSVProcessorOptions;
+    /** PDF processing options (#258). */
+    pdfOptions?: {
+        /** Password for an encrypted PDF (image-conversion fallback path). */
+        password?: string;
+        /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
+        maxCanvasPixels?: number;
+    };
     videoOptions?: {
         frames?: number;
         quality?: number;

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

@@ -39,6 +39,8 @@ export declare const ERROR_CODES: {
     readonly FILE_PROCESSING_FAILED: "FILE_PROCESSING_FAILED";
     readonly CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED";
     readonly PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED";
+    readonly PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED";
+    readonly PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD";
     readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
     readonly RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT";
     readonly RATE_LIMITER_RESET: "RATE_LIMITER_RESET";
@@ -199,6 +201,14 @@ export declare class ErrorFactory {
      * Create a PDF page limit exceeded error
      */
     static pdfPageLimitExceeded(estimatedPages: number, maxPages: number, provider: string): NeuroLinkError;
+    /**
+     * The PDF is encrypted and no password was supplied (#258).
+     */
+    static pdfPasswordRequired(): NeuroLinkError;
+    /**
+     * A password was supplied for an encrypted PDF but it was incorrect (#258).
+     */
+    static pdfIncorrectPassword(): NeuroLinkError;
     /**
      * Create an image too large error
      */

package/dist/lib/utils/errorHandling.js

@@ -52,6 +52,8 @@ export const ERROR_CODES = {
     CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED",
     // PDF validation errors
     PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
+    PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED",
+    PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD",
     // Rate limiter errors
     RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL",
     RATE_LIMITER_QUEUE_TIMEOUT: "RATE_LIMITER_QUEUE_TIMEOUT",
@@ -553,6 +555,32 @@ export class ErrorFactory {
             },
         });
     }
+    /**
+     * The PDF is encrypted and no password was supplied (#258).
+     */
+    static pdfPasswordRequired() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_PASSWORD_REQUIRED,
+            message: "This PDF is password-protected. Supply the password via " +
+                "`pdfOptions: { password: '…' }` (SDK) or `--pdf-password` (CLI).",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+        });
+    }
+    /**
+     * A password was supplied for an encrypted PDF but it was incorrect (#258).
+     */
+    static pdfIncorrectPassword() {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_INCORRECT_PASSWORD,
+            message: "The password supplied for this PDF is incorrect. Check the " +
+                "`pdfOptions.password` / `--pdf-password` value and try again.",
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+        });
+    }
     /**
      * Create an image too large error
      */

package/dist/lib/utils/fileDetector.js

@@ -1413,6 +1413,41 @@ export class FileDetector {
         const timeout = options?.timeout || FileDetector.DEFAULT_NETWORK_TIMEOUT;
         const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
         const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY;
+        // #317: pre-flight HEAD to reject an oversized file BEFORE downloading any
+        // body. content-length is advisory (chunked responses omit it), so a
+        // missing/invalid header — or a server that refuses HEAD — falls through to
+        // the streaming byte guard below; only a genuine oversize rejection stops
+        // the GET from ever running.
+        //
+        // #323: skip the pre-flight entirely when this exact URL was recently seen
+        // (its Content-Type is still cached, whether from a prior loadFromURL GET
+        // or a MimeTypeStrategy HEAD) — issuing a fresh HEAD here would defeat the
+        // whole point of that cache. The streaming byte guard in the GET below
+        // still enforces maxSize even without a pre-flight, so this doesn't remove
+        // the oversize protection — it only skips the redundant round-trip for a
+        // URL we've already been talking to within the last 60s.
+        if (getCachedUrlContentType(url, Date.now()) === undefined) {
+            try {
+                const head = await request(url, {
+                    dispatcher: getGlobalDispatcher().compose(interceptors.redirect({ maxRedirections: 5 })),
+                    method: "HEAD",
+                    headersTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                    bodyTimeout: FileDetector.DEFAULT_HEAD_TIMEOUT,
+                });
+                // Drain/close the (empty) HEAD body so the connection can be reused.
+                await head.body.dump();
+                const declaredLength = Number(head.headers["content-length"]);
+                if (Number.isFinite(declaredLength) && declaredLength > maxSize) {
+                    throw new Error(`File too large: ${formatFileSize(declaredLength)} (max: ${formatFileSize(maxSize)})`);
+                }
+            }
+            catch (error) {
+                if (error instanceof Error && /File too large/.test(error.message)) {
+                    throw error;
+                }
+                logger.debug(`[FileDetector] HEAD pre-flight skipped for ${url}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
         return withRetry(async () => {
             try {
                 const response = await request(url, {

package/dist/lib/utils/messageBuilder.js

@@ -1011,6 +1011,12 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
                     buffer: result.content,
                     filename,
                     pageCount: result.metadata?.estimatedPages ?? null,
+                    // #258: carry the password so the image-fallback conversion can
+                    // decrypt an encrypted PDF for providers without native PDF support.
+                    password: options.pdfOptions?.password,
+                    // #260: carry the per-page canvas-pixel ceiling so the caller can
+                    // raise (or lower) the memory guard for the image-fallback render.
+                    maxCanvasPixels: options.pdfOptions?.maxCanvasPixels,
                 });
                 logger.info(`[PDF] ✅ Queued for multimodal: ${filename} (${result.metadata?.estimatedPages ?? "unknown"} pages)`);
             }
@@ -1020,6 +1026,23 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
             throw error;
         }
     }
+    // #309: enforce the provider's page/size ceilings across ALL PDFs, not just
+    // per-file. N files each just under the single-file limit can still blow past
+    // it in aggregate (e.g. three 40-page PDFs → 120 pages for a 100-page API).
+    const aggregateConfig = PDFProcessor.getProviderConfig(provider);
+    if (aggregateConfig && pdfFiles.length > 1) {
+        const totalPages = pdfFiles.reduce((sum, f) => sum + (f.pageCount ?? 0), 0);
+        const totalMB = pdfFiles.reduce((sum, f) => sum + f.buffer.length, 0) / (1024 * 1024);
+        if (totalPages > aggregateConfig.maxPages) {
+            throw new Error(`[PDF] Combined page count across ${pdfFiles.length} PDFs (${totalPages}) exceeds the ` +
+                `${aggregateConfig.maxPages}-page limit for ${provider}. ` +
+                `Split the request or reduce the number of PDFs.`);
+        }
+        if (totalMB > aggregateConfig.maxSizeMB) {
+            throw new Error(`[PDF] Combined size across ${pdfFiles.length} PDFs (${totalMB.toFixed(2)}MB) exceeds the ` +
+                `${aggregateConfig.maxSizeMB}MB limit for ${provider}.`);
+        }
+    }
     return pdfFiles;
 }
 /**
@@ -1103,7 +1126,13 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     // Check if this is a multimodal request
     const hasImages = (inp.images && inp.images.length > 0) ||
         (inp.content && inp.content.some((c) => c.type === "image"));
-    const hasPDFs = pdfFiles.length > 0;
+    // A PDF supplied only via input.content (type: "pdf", no explicit
+    // input.pdfFiles and no image alongside it) must still route through the
+    // multimodal path below — otherwise it silently falls through to the
+    // text-only branch and the PDF (and any pdfOptions) never reaches
+    // convertContentToProviderFormat at all.
+    const hasPDFs = pdfFiles.length > 0 ||
+        !!(inp.content && inp.content.some((c) => c.type === "pdf"));
     // If no images or PDFs, use standard message building and convert to MultimodalChatMessage[]
     if (!hasImages && !hasPDFs) {
         // #289: CSV content[] items don't need vision, so they never reach the
@@ -1139,8 +1168,11 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
             `Supported providers: ${ProviderImageAdapter.getVisionProviders().join(", ")}`);
     }
     const messages = [];
-    // Build enhanced system prompt
-    const systemPrompt = buildMultimodalSystemPrompt(options, pdfFiles.length > 0);
+    // Build enhanced system prompt. Gate on the same `hasPDFs` predicate used
+    // for routing above — a PDF supplied only via input.content (no explicit
+    // input.pdfFiles) must still get the "treat inlined content as an
+    // attachment" instruction, or the model can claim no files were attached.
+    const systemPrompt = buildMultimodalSystemPrompt(options, hasPDFs);
     if (systemPrompt.trim()) {
         messages.push({
             role: "system",
@@ -1206,7 +1238,7 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     try {
         let userContent;
         if (inp.content && inp.content.length > 0) {
-            userContent = await convertContentToProviderFormat(inp.content, provider, model);
+            userContent = await convertContentToProviderFormat(inp.content, provider, model, options.pdfOptions);
         }
         else if ((inp.images && inp.images.length > 0) || pdfFiles.length > 0) {
             userContent = await convertMultimodalToProviderFormat(inp.text ?? "", inp.images || [], pdfFiles, provider, model);
@@ -1285,7 +1317,7 @@ async function appendCsvContentToText(csvItems, baseText) {
 /**
  * Convert advanced content format to provider-specific format
  */
-async function convertContentToProviderFormat(content, provider, _model) {
+async function convertContentToProviderFormat(content, provider, _model, pdfOptions) {
     const textContent = content.find((c) => c.type === "text");
     const imageContent = content.filter((c) => c.type === "image");
     const pdfContent = content.filter((c) => c.type === "pdf");
@@ -1312,6 +1344,11 @@ async function convertContentToProviderFormat(content, provider, _model) {
         buffer: typeof pdf.data === "string" ? Buffer.from(pdf.data, "base64") : pdf.data,
         filename: pdf.metadata?.filename || "document.pdf",
         pageCount: pdf.metadata?.pages ?? null,
+        // #258/#260: carry password + canvas-pixel ceiling so a PDF supplied via
+        // the advanced `input.content` array gets the same decryption/memory
+        // guard as the `input.pdfFiles` path (see `processExplicitPdfFiles`).
+        password: pdfOptions?.password,
+        maxCanvasPixels: pdfOptions?.maxCanvasPixels,
     }));
     return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, _model);
 }
@@ -1694,6 +1731,10 @@ async function convertMultimodalToProviderFormat(text, images, pdfFiles, provide
                 const conversionResult = await PDFImageConverter.convertToImages(pdf.buffer, {
                     scale: 2.0, // High quality for OCR/analysis
                     maxPages: 20, // Limit pages to prevent token overflow
+                    ...(pdf.password ? { password: pdf.password } : {}), // #258
+                    ...(pdf.maxCanvasPixels
+                        ? { maxCanvasPixels: pdf.maxCanvasPixels }
+                        : {}), // #260
                 });
                 logger.info(`[PDF→Image] ✅ Converted ${pdf.filename}: ${conversionResult.pageCount} page(s) → images`);
                 // Add each page as an ImagePart (raw base64, not data: URI — see SSRF note above)
@@ -1715,6 +1756,13 @@ async function convertMultimodalToProviderFormat(text, images, pdfFiles, provide
             catch (error) {
                 const errorMessage = error instanceof Error ? error.message : String(error);
                 logger.error(`[PDF→Image] ❌ Failed to convert ${pdf.filename}: ${errorMessage}`);
+                // #258: password errors are already actionable typed errors — re-throw
+                // them unwrapped so the "supply a password" guidance isn't buried.
+                const code = error?.code;
+                if (code === "PDF_PASSWORD_REQUIRED" ||
+                    code === "PDF_INCORRECT_PASSWORD") {
+                    throw error;
+                }
                 // Re-throw so the user knows PDF processing failed
                 throw new Error(`PDF to image conversion failed for ${pdf.filename}: ${errorMessage}. ` +
                     `Provider ${provider} doesn't support native PDFs and image conversion failed.`, { cause: error });

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

@@ -51,6 +51,10 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
         pdfFiles: (string | Buffer<ArrayBufferLike>)[] | undefined;
     };
     csvOptions: import("../types/file.js").CSVProcessorOptions | undefined;
+    pdfOptions: {
+        password?: string;
+        maxCanvasPixels?: number;
+    } | undefined;
     systemPrompt: string | undefined;
     conversationHistory: import("../types/conversation.js").ChatMessage[] | undefined;
     provider: string;

package/dist/lib/utils/multimodalOptionsBuilder.js

@@ -51,6 +51,7 @@ export function buildMultimodalOptions(options, providerName, modelName) {
             pdfFiles: options.input?.pdfFiles,
         },
         csvOptions: options.csvOptions,
+        pdfOptions: options.pdfOptions,
         systemPrompt: options.systemPrompt,
         conversationHistory: options.conversationMessages,
         provider: providerName,