@juspay/neurolink 10.10.7 → 10.10.8

package/dist/cli/factories/commandFactory.js

@@ -166,15 +166,19 @@ export class CLICommandFactory {
             type: "string",
             description: "Add video file for analysis (can be used multiple times) (MP4, WebM, MOV, AVI, MKV)",
         },
+        // No yargs `default:` on these two. They used to declare 8 / 85 while the
+        // processor actually picks a duration-based frame count (up to 100) and
+        // encodes at quality 80 — harmless only because the values were never read
+        // (#478). Now that they reach the encoder, a default here would silently
+        // re-cap every existing CLI video at 8 frames. Unset means "let the
+        // processor choose", which is what callers have always effectively had.
         "video-frames": {
             type: "number",
-            default: 8,
-            description: "Number of frames to extract (default: 8)",
+            description: "Number of frames to extract (default: chosen from video duration, max 100)",
         },
         "video-quality": {
             type: "number",
-            default: 85,
-            description: "Frame quality 0-100 (default: 85)",
+            description: "Frame quality 1-100 (default: 80)",
         },
         "video-format": {
             type: "string",

package/dist/lib/processors/media/VideoProcessor.d.ts

@@ -44,7 +44,7 @@
  * ```
  */
 import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
-import type { FileInfo, ProcessedVideo, ProcessorFileProcessingResult, ProcessOptions } from "../../types/index.js";
+import type { FileInfo, ProcessedVideo, ProcessorFileProcessingResult, ProcessOptions, VideoProcessorOptions } from "../../types/index.js";
 /**
  * Narrow a loaded `fluent-ffmpeg` export to the shape this file actually uses:
  * a callable carrying the `ffprobe` and `setFfmpegPath` statics.
@@ -116,7 +116,7 @@ export declare class VideoProcessor extends BaseFileProcessor<ProcessedVideo> {
      * @param options - Optional processing options
      * @returns Processing result with extracted video data or error
      */
-    processFile(fileInfo: FileInfo, options?: ProcessOptions): Promise<ProcessorFileProcessingResult<ProcessedVideo>>;
+    processFile(fileInfo: FileInfo, options?: ProcessOptions & VideoProcessorOptions): Promise<ProcessorFileProcessingResult<ProcessedVideo>>;
     /**
      * Probe a video file to extract metadata using ffprobe.
      *
@@ -137,6 +137,11 @@ export declare class VideoProcessor extends BaseFileProcessor<ProcessedVideo> {
      * @returns Structured video metadata
      */
     private buildMetadata;
+    /**
+     * Clamp a caller-supplied frame quality into sharp's valid 1-100 range,
+     * falling back to the default when absent or non-numeric (#478).
+     */
+    private static resolveFrameQuality;
     /**
      * Extract keyframes from a video at calculated intervals.
      *
@@ -153,10 +158,15 @@ export declare class VideoProcessor extends BaseFileProcessor<ProcessedVideo> {
      * The interval is adaptive: if the tier interval would exceed MAX_FRAMES,
      * the interval widens to duration/MAX_FRAMES for full-video coverage.
      *
+     * A caller-supplied `options.frames` overrides the tier schedule entirely:
+     * that many frames are spread evenly across the clip, still capped at
+     * MAX_FRAMES. `options.quality` and `options.format` reach the encoder (#478).
+     *
      * @param videoPath - Path to the video file
      * @param tempDir - Temp directory for frame output
      * @param durationSec - Video duration in seconds
-     * @returns Array of JPEG frame buffers
+     * @param options - Caller frame budget / encoder settings
+     * @returns Array of encoded frame buffers (JPEG unless png was requested)
      */
     private extractKeyframes;
     /**

package/dist/lib/processors/media/VideoProcessor.js

@@ -313,7 +313,10 @@ export class VideoProcessor extends BaseFileProcessor {
      * @param options - Optional processing options
      * @returns Processing result with extracted video data or error
      */
-    async processFile(fileInfo, options) {
+    async processFile(fileInfo, 
+    // #478: widened with the keyframe knobs so `--video-frames`/`-quality`/
+    // `-format` can reach the encoder instead of being silently discarded.
+    options) {
         const filename = this.getFilename(fileInfo);
         const sizeBytes = fileInfo.size || fileInfo.buffer?.length || 0;
         return withSpan({
@@ -438,7 +441,7 @@ export class VideoProcessor extends BaseFileProcessor {
                 // Step 5: Extract keyframes
                 let keyframes = [];
                 try {
-                    keyframes = await this.extractKeyframes(tempVideoPath, tempDir, metadata.duration);
+                    keyframes = await this.extractKeyframes(tempVideoPath, tempDir, metadata.duration, options);
                 }
                 catch {
                     // Non-fatal: continue without keyframes if extraction fails
@@ -642,6 +645,16 @@ export class VideoProcessor extends BaseFileProcessor {
     // ===========================================================================
     // KEYFRAME EXTRACTION
     // ===========================================================================
+    /**
+     * Clamp a caller-supplied frame quality into sharp's valid 1-100 range,
+     * falling back to the default when absent or non-numeric (#478).
+     */
+    static resolveFrameQuality(quality) {
+        if (typeof quality !== "number" || !Number.isFinite(quality)) {
+            return VIDEO_CONFIG.FRAME_JPEG_QUALITY;
+        }
+        return Math.min(100, Math.max(1, Math.round(quality)));
+    }
     /**
      * Extract keyframes from a video at calculated intervals.
      *
@@ -658,20 +671,45 @@ export class VideoProcessor extends BaseFileProcessor {
      * The interval is adaptive: if the tier interval would exceed MAX_FRAMES,
      * the interval widens to duration/MAX_FRAMES for full-video coverage.
      *
+     * A caller-supplied `options.frames` overrides the tier schedule entirely:
+     * that many frames are spread evenly across the clip, still capped at
+     * MAX_FRAMES. `options.quality` and `options.format` reach the encoder (#478).
+     *
      * @param videoPath - Path to the video file
      * @param tempDir - Temp directory for frame output
      * @param durationSec - Video duration in seconds
-     * @returns Array of JPEG frame buffers
+     * @param options - Caller frame budget / encoder settings
+     * @returns Array of encoded frame buffers (JPEG unless png was requested)
      */
-    async extractKeyframes(videoPath, tempDir, durationSec) {
+    async extractKeyframes(videoPath, tempDir, durationSec, options) {
         if (durationSec <= 0) {
             return [];
         }
-        // Determine extraction interval based on duration
-        const intervalSec = this.getFrameInterval(durationSec);
+        // #478: honor the caller's frame budget, still bounded by MAX_FRAMES so a
+        // CLI flag can lower the cost but never raise it past the processor's own
+        // ceiling. A non-positive/non-finite request falls back to the default.
+        const requestedFrames = options?.frames;
+        const hasExplicitBudget = typeof requestedFrames === "number" &&
+            Number.isFinite(requestedFrames) &&
+            requestedFrames > 0;
+        const frameBudget = hasExplicitBudget
+            ? Math.min(Math.floor(requestedFrames), VIDEO_CONFIG.MAX_FRAMES)
+            : VIDEO_CONFIG.MAX_FRAMES;
+        // Determine extraction interval based on duration. When the caller asked
+        // for a specific frame count, spread that many evenly across the whole
+        // video instead of using the duration tier — otherwise a short interval
+        // would hit the budget early and only cover the opening seconds.
+        //
+        // Keyed on whether a budget was REQUESTED, not on whether it happens to be
+        // below MAX_FRAMES: asking for exactly MAX_FRAMES is still an explicit
+        // request and must produce that many frames, not silently fall back to the
+        // tier schedule (which yields far fewer on a short clip).
+        const intervalSec = hasExplicitBudget
+            ? Math.max(durationSec / frameBudget, Number.EPSILON)
+            : this.getFrameInterval(durationSec);
         // Calculate timestamps to extract
         const timestamps = [];
-        for (let t = 0; t < durationSec && timestamps.length < VIDEO_CONFIG.MAX_FRAMES; t += intervalSec) {
+        for (let t = 0; t < durationSec && timestamps.length < frameBudget; t += intervalSec) {
             timestamps.push(t);
         }
         if (timestamps.length === 0) {
@@ -691,13 +729,16 @@ export class VideoProcessor extends BaseFileProcessor {
                 const rawFrame = await fs.readFile(framePath);
                 // Resize to fit within max dimension while preserving aspect ratio
                 const sharp = (await import("sharp")).default;
-                const resized = await sharp(rawFrame)
-                    .resize(VIDEO_CONFIG.FRAME_MAX_DIMENSION, VIDEO_CONFIG.FRAME_MAX_DIMENSION, {
+                const pipeline = sharp(rawFrame).resize(VIDEO_CONFIG.FRAME_MAX_DIMENSION, VIDEO_CONFIG.FRAME_MAX_DIMENSION, {
                     fit: "inside",
                     withoutEnlargement: true,
-                })
-                    .jpeg({ quality: VIDEO_CONFIG.FRAME_JPEG_QUALITY })
-                    .toBuffer();
+                });
+                // #478: `--video-quality` / `--video-format` were accepted by the CLI
+                // and then dropped on the floor; both now reach the encoder.
+                const quality = VideoProcessor.resolveFrameQuality(options?.quality);
+                const resized = await (options?.format === "png"
+                    ? pipeline.png({ quality })
+                    : pipeline.jpeg({ quality })).toBuffer();
                 keyframes.push(resized);
             }
             catch {

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

@@ -302,6 +302,21 @@ export type AudioProcessorOptions = {
     /** Maximum file size in megabytes */
     maxSizeMB?: number;
 };
+/**
+ * Keyframe-extraction knobs for an attached video (#478).
+ *
+ * These back the `--video-frames` / `--video-quality` / `--video-format` CLI
+ * flags and `GenerateOptions.videoOptions`. Each is clamped to the processor's
+ * own ceiling — a caller cannot raise `frames` above VIDEO_CONFIG.MAX_FRAMES.
+ */
+export type VideoProcessorOptions = {
+    /** Max keyframes to extract. Clamped to the processor's MAX_FRAMES ceiling. */
+    frames?: number;
+    /** Encoder quality 1-100 for the extracted frames. */
+    quality?: number;
+    /** Frame encoding. Defaults to jpeg. */
+    format?: "jpeg" | "png";
+};
 /**
  * Office processor options for Word, PowerPoint, and Excel documents
  *
@@ -366,6 +381,7 @@ export type FileDetectorOptions = {
     audioOptions?: AudioProcessorOptions;
     csvOptions?: CSVProcessorOptions;
     officeOptions?: OfficeProcessorOptions;
+    videoOptions?: VideoProcessorOptions;
     confidenceThreshold?: number;
     provider?: string;
     /** Maximum number of retry attempts for network requests (default: 3) */
@@ -438,6 +454,27 @@ export type PDFImagePage = {
     /** Populated when this page failed to render (#294). */
     error?: string;
 };
+/**
+ * A single PDF queued for multimodal message building, normalised from either
+ * submission surface — `input.pdfFiles` or `input.content` with `type: "pdf"`
+ * — so both can share the aggregate page/size guard (#309).
+ */
+export type MultimodalPdfEntry = {
+    /** Raw PDF bytes. */
+    buffer: Buffer;
+    /** Display name; may be a full path, so log only its basename. */
+    filename: string;
+    /**
+     * Page count when known. Null/undefined on the `input.content` path whenever
+     * the caller omitted `metadata.pages`; the aggregate guard resolves those
+     * from `buffer` rather than treating them as zero.
+     */
+    pageCount?: number | null;
+    /** Password for an encrypted PDF (#258). */
+    password?: string;
+    /** Per-page pixel ceiling for the image fallback (#260). */
+    maxCanvasPixels?: number;
+};
 /** Result of PDF to image conversion. */
 export type PDFImageConversionResult = {
     /** Array of base64-encoded PNG images (one per successfully converted page) */

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

@@ -135,9 +135,13 @@ export type GenerateOptions = {
         maxCanvasPixels?: number;
     };
     videoOptions?: {
+        /** Frames to extract. Unset lets VideoProcessor pick from the clip's duration; clamped to 100. */
         frames?: number;
+        /** Frame encoder quality, clamped to 1-100. Default 80. */
         quality?: number;
+        /** Frame encoding. Default jpeg. */
         format?: "jpeg" | "png";
+        /** Not implemented yet (#433) — warns rather than silently doing nothing. */
         transcribeAudio?: boolean;
     };
     /**

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

@@ -227,9 +227,13 @@ export type StreamOptions = {
         maxCanvasPixels?: number;
     };
     videoOptions?: {
+        /** Frames to extract. Unset lets VideoProcessor pick from the clip's duration; clamped to 100. */
         frames?: number;
+        /** Frame encoder quality, clamped to 1-100. Default 80. */
         quality?: number;
+        /** Frame encoding. Default jpeg. */
         format?: "jpeg" | "png";
+        /** Not implemented yet (#433) — warns rather than silently doing nothing. */
         transcribeAudio?: boolean;
     };
     /**

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

@@ -39,6 +39,9 @@ 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_AGGREGATE_PAGE_LIMIT_EXCEEDED: "PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED";
+    readonly PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED: "PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED";
+    readonly PDF_PAGE_COUNT_UNVERIFIABLE: "PDF_PAGE_COUNT_UNVERIFIABLE";
     readonly PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED";
     readonly PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD";
     readonly RATE_LIMITER_QUEUE_FULL: "RATE_LIMITER_QUEUE_FULL";
@@ -203,6 +206,24 @@ export declare class ErrorFactory {
      * Create a PDF page limit exceeded error
      */
     static pdfPageLimitExceeded(estimatedPages: number, maxPages: number, provider: string): NeuroLinkError;
+    /**
+     * The combined page count across every PDF in one request exceeds what the
+     * provider accepts (#309). Distinct from `pdfPageLimitExceeded`, which is
+     * per-file — here each document can be individually legal.
+     */
+    static pdfAggregatePageLimitExceeded(fileCount: number, totalPages: number, maxPages: number, provider: string): NeuroLinkError;
+    /**
+     * The combined byte size across every PDF in one request exceeds what the
+     * provider accepts (#309).
+     */
+    static pdfAggregateSizeLimitExceeded(fileCount: number, totalMB: number, maxSizeMB: number, provider: string): NeuroLinkError;
+    /**
+     * A PDF supplied through the untrusted `input.content` surface could not be
+     * parsed for a page count (#309). Caller-supplied `metadata.pages` is not
+     * authoritative there, so an unreadable document is rejected rather than
+     * admitted with an assumed count of zero.
+     */
+    static pdfPageCountUnverifiable(filenames: string[], provider: string): NeuroLinkError;
     /**
      * The PDF is encrypted and no password was supplied (#258).
      */

package/dist/lib/utils/errorHandling.js

@@ -52,6 +52,9 @@ export const ERROR_CODES = {
     CSV_PROCESSING_FAILED: "CSV_PROCESSING_FAILED",
     // PDF validation errors
     PDF_PAGE_LIMIT_EXCEEDED: "PDF_PAGE_LIMIT_EXCEEDED",
+    PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED: "PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED",
+    PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED: "PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED",
+    PDF_PAGE_COUNT_UNVERIFIABLE: "PDF_PAGE_COUNT_UNVERIFIABLE",
     PDF_PASSWORD_REQUIRED: "PDF_PASSWORD_REQUIRED",
     PDF_INCORRECT_PASSWORD: "PDF_INCORRECT_PASSWORD",
     // Rate limiter errors
@@ -557,6 +560,56 @@ export class ErrorFactory {
             },
         });
     }
+    /**
+     * The combined page count across every PDF in one request exceeds what the
+     * provider accepts (#309). Distinct from `pdfPageLimitExceeded`, which is
+     * per-file — here each document can be individually legal.
+     */
+    static pdfAggregatePageLimitExceeded(fileCount, totalPages, maxPages, provider) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_AGGREGATE_PAGE_LIMIT_EXCEEDED,
+            message: `[PDF] Combined page count across ${fileCount} PDF(s) (${totalPages}) exceeds the ` +
+                `${maxPages}-page limit for ${provider}. ` +
+                `Split the request or reduce the number of PDFs.`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { fileCount, totalPages, maxPages, provider },
+        });
+    }
+    /**
+     * The combined byte size across every PDF in one request exceeds what the
+     * provider accepts (#309).
+     */
+    static pdfAggregateSizeLimitExceeded(fileCount, totalMB, maxSizeMB, provider) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_AGGREGATE_SIZE_LIMIT_EXCEEDED,
+            message: `[PDF] Combined size across ${fileCount} PDF(s) (${totalMB.toFixed(2)}MB) exceeds the ` +
+                `${maxSizeMB}MB limit for ${provider}.`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { fileCount, totalMB, maxSizeMB, provider },
+        });
+    }
+    /**
+     * A PDF supplied through the untrusted `input.content` surface could not be
+     * parsed for a page count (#309). Caller-supplied `metadata.pages` is not
+     * authoritative there, so an unreadable document is rejected rather than
+     * admitted with an assumed count of zero.
+     */
+    static pdfPageCountUnverifiable(filenames, provider) {
+        return new NeuroLinkError({
+            code: ERROR_CODES.PDF_PAGE_COUNT_UNVERIFIABLE,
+            message: `[PDF] Cannot verify the page count for ${filenames.length} PDF(s) supplied via ` +
+                `input.content (${filenames.join(", ")}). Provide readable PDFs, or submit them ` +
+                `via input.pdfFiles where page counts are derived during detection.`,
+            category: ErrorCategory.VALIDATION,
+            severity: ErrorSeverity.MEDIUM,
+            retriable: false,
+            context: { filenames, provider },
+        });
+    }
     /**
      * The PDF is encrypted and no password was supplied (#258).
      */

package/dist/lib/utils/fileDetector.js

@@ -344,13 +344,13 @@ export class FileDetector {
                 logger.warn(`[FileDetector] All fallback parsing failed for type "${detection.type}". ` +
                     `Attempted: ${options.allowedTypes.join(", ")}. Falling through to universal handler.`);
                 const csvOptions = options?.csvOptions;
-                const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider);
+                const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider, options?.videoOptions);
                 FileDetector.setFileResultSpanAttributes(span, result, inputFilename, detection.type);
                 return result;
             }
             const content = await FileDetector.loadContent(input, detection, options);
             const csvOptions = options?.csvOptions;
-            const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider);
+            const result = await FileDetector.processFile(content, detection, csvOptions, options?.provider, options?.videoOptions);
             FileDetector.setFileResultSpanAttributes(span, result, inputFilename, detection.type);
             return result;
         });
@@ -967,7 +967,7 @@ export class FileDetector {
     /**
      * Route to appropriate processor
      */
-    static async processFile(content, detection, options, provider) {
+    static async processFile(content, detection, options, provider, videoOptions) {
         switch (detection.type) {
             case "csv":
                 // Pass original extension through to CSV processor; if detection has none,
@@ -985,7 +985,7 @@ export class FileDetector {
                 // AI providers don't support SVG as image format, so we extract text content
                 return await FileDetector.processSvgAsText(content, detection);
             case "video":
-                return await FileDetector.processVideoFile(content, detection);
+                return await FileDetector.processVideoFile(content, detection, videoOptions);
             case "audio":
                 return await FileDetector.processAudioFile(content, detection);
             case "archive":
@@ -1031,7 +1031,7 @@ export class FileDetector {
     /**
      * Process video file: extract metadata, keyframes, and subtitles via VideoProcessor
      */
-    static async processVideoFile(content, detection) {
+    static async processVideoFile(content, detection, videoOptions) {
         const videoFilename = detection.metadata.filename || "video";
         try {
             const videoResult = await (await getVideoProcessor()).processFile({
@@ -1040,7 +1040,10 @@ export class FileDetector {
                 mimetype: detection.mimeType || "video/mp4",
                 size: content.length,
                 buffer: content,
-            });
+            }, 
+            // #478: carry the caller's keyframe budget/quality/format through to
+            // the processor; previously these stopped at the CLI layer.
+            videoOptions);
             if (videoResult.success && videoResult.data) {
                 return {
                     type: "video",

package/dist/lib/utils/messageBuilder.js

@@ -1,6 +1,5 @@
 import { existsSync, readFileSync, statSync } from "fs";
 import { readFile as readFileAsync, stat as statAsync } from "fs/promises";
-import { basename } from "path";
 import { getGlobalDispatcher, interceptors, request } from "undici";
 import { MultimodalLogger, ProviderImageAdapter, } from "../adapters/providerImageAdapter.js";
 import { CONVERSATION_INSTRUCTIONS, STRUCTURED_OUTPUT_INSTRUCTIONS, } from "../config/conversationMemory.js";
@@ -809,6 +808,20 @@ export function mergeMediaFileAliases(input) {
     input.audioFiles = undefined;
     input.videoFiles = undefined;
 }
+/**
+ * #478: `transcribeAudio` (CLI `--transcribe-audio`) is accepted by the options
+ * surface but no video-audio transcription exists yet — VideoProcessor extracts
+ * keyframes and embedded subtitle tracks only, and the transcription step is
+ * still open as #433. Say so once per request rather than letting the caller
+ * believe a transcript was produced and silently omitted.
+ */
+function warnIfVideoTranscriptionRequested(videoOptions) {
+    if (videoOptions?.transcribeAudio) {
+        logger.warn("[NEUROLINK] Video audio transcription was requested but is not implemented yet " +
+            "(tracked as #433). Keyframes and any embedded subtitle tracks are still extracted; " +
+            "spoken audio will not be transcribed.");
+    }
+}
 /**
  * Process the unified files array with auto-detection.
  * Handles lazy file registration, full processing, and preview injection.
@@ -825,6 +838,7 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
     }
     const totalFiles = options.input.files.length;
     const files = options.input.files;
+    warnIfVideoTranscriptionRequested(options.videoOptions);
     return withSpan({
         name: "neurolink.file.process_all",
         tracer: tracers.file,
@@ -882,6 +896,15 @@ export async function processUnifiedFilesArray(options, maxSize, provider) {
                         "unknown",
                     ],
                     csvOptions: options.csvOptions,
+                    // #478: videos arrive through this unified `files` path, so this is
+                    // where the CLI's frame/quality/format request has to be handed on.
+                    videoOptions: options.videoOptions
+                        ? {
+                            frames: options.videoOptions.frames,
+                            quality: options.videoOptions.quality,
+                            format: options.videoOptions.format,
+                        }
+                        : undefined,
                     provider: provider,
                     mimetypeHint: fileMimetypeHint,
                 });
@@ -1020,6 +1043,83 @@ function enforcePostProcessingBudget(options, provider, model) {
         `budget=${contextWindow.toLocaleString()} tokens, ` +
         `utilization=${contextWindow > 0 ? ((totalContentTokens / contextWindow) * 100).toFixed(1) : "N/A"}%`);
 }
+/**
+ * #309: enforce the provider's page/size ceilings across ALL PDFs in a request,
+ * 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).
+ *
+ * Shared by both PDF submission surfaces: `input.pdfFiles` (via
+ * `processExplicitPdfFiles`) and `input.content` with `type: "pdf"` (via
+ * `convertContentToProviderFormat`). The latter previously built its own
+ * `pdfFiles` array and reached the provider without ever calling this guard,
+ * so the limit was bypassable by moving the same payload to `input.content`.
+ */
+/**
+ * Basename that strips BOTH separators regardless of host platform.
+ *
+ * `path.basename` only understands the host's separator, so on a POSIX server
+ * a Windows-style filename (`C:\Users\alice\q3-merger.pdf`) comes back
+ * completely unchanged — defeating the point of trimming it before it reaches
+ * a log line, since caller-controlled paths can carry usernames and internal
+ * directory structure.
+ */
+function safeBasename(filename) {
+    const lastSeparator = Math.max(filename.lastIndexOf("/"), filename.lastIndexOf("\\"));
+    const trimmed = lastSeparator === -1 ? filename : filename.slice(lastSeparator + 1);
+    return trimmed || "<unnamed file>";
+}
+async function enforceAggregatePdfLimits(pdfFiles, provider, { trustSuppliedPageCounts }) {
+    const aggregateConfig = PDFProcessor.getProviderConfig(provider);
+    // Only an empty set is exempt. A single PDF must still be checked: on the
+    // `input.content` path nothing else validates it (that path never goes
+    // through FileDetector.detectAndProcess / PDFProcessor.process), so bailing
+    // at length <= 1 let one 200-page document through untouched.
+    if (!aggregateConfig || pdfFiles.length === 0) {
+        return;
+    }
+    // Byte total is free to compute — enforce it BEFORE parsing anything, so an
+    // oversized request is rejected without first spending parser CPU/memory on
+    // every document in it.
+    const totalMB = pdfFiles.reduce((sum, f) => sum + f.buffer.length, 0) / (1024 * 1024);
+    if (totalMB > aggregateConfig.maxSizeMB) {
+        throw ErrorFactory.pdfAggregateSizeLimitExceeded(pdfFiles.length, totalMB, aggregateConfig.maxSizeMB, provider);
+    }
+    // `trustSuppliedPageCounts` is the difference between the two surfaces.
+    // On `input.pdfFiles` the count comes from FileDetector's own detection, so
+    // it is authoritative. On `input.content` it is `metadata.pages` — plain
+    // caller input — and trusting it lets a request declare `pages: 1` for each
+    // of three 40-page PDFs and sail past the ceiling. There, the count is
+    // always re-derived from the bytes and the supplied value is ignored.
+    const pageCounts = await Promise.all(pdfFiles.map(async (f) => trustSuppliedPageCounts && typeof f.pageCount === "number"
+        ? f.pageCount
+        : await PDFProcessor.resolvePageCount(f.buffer)));
+    // Filenames are caller-controlled and may be full paths carrying
+    // PII/internal directory segments — surface only the basename, stripping
+    // both separators so a Windows path is trimmed on a POSIX host too.
+    const unknownFileNames = pdfFiles
+        .filter((_, i) => typeof pageCounts[i] !== "number")
+        .map((f) => (f.filename ? safeBasename(f.filename) : "<unnamed file>"));
+    const totalPages = pageCounts.reduce((sum, p) => sum + (typeof p === "number" ? p : 0), 0);
+    if (unknownFileNames.length > 0) {
+        if (!trustSuppliedPageCounts) {
+            // Untrusted surface: an unreadable count is indistinguishable from an
+            // evasion attempt, and counting it as zero is precisely the hole. Fail
+            // closed rather than admit an unverifiable document.
+            throw ErrorFactory.pdfPageCountUnverifiable(unknownFileNames, provider);
+        }
+        // Trusted surface: detection already vetted these, so one unreadable
+        // count must not fail an otherwise valid request — but it must not be
+        // silent either, since the known sum may undercount the true total.
+        logger.warn(`[PDF] Aggregate page-limit check across ${pdfFiles.length} PDFs could only be ` +
+            `partially verified: ${unknownFileNames.length} file(s) have an unknown ` +
+            `page count (${unknownFileNames.join(", ")}), so the known total (${totalPages}) may ` +
+            `undercount the true combined page count.`);
+    }
+    if (totalPages > aggregateConfig.maxPages) {
+        throw ErrorFactory.pdfAggregatePageLimitExceeded(pdfFiles.length, totalPages, aggregateConfig.maxPages, provider);
+    }
+}
 /**
  * Process explicit PDF files and return structured PDF entries for multimodal processing.
  */
@@ -1059,41 +1159,10 @@ 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) {
-        // A null pageCount (accurate count unavailable — see
-        // PDFProcessor.getAccuratePageCount) is treated as 0 in the sum below,
-        // which can undercount the aggregate and let a combined request over
-        // the provider's page limit slip through silently. Enforcement still
-        // runs against the known sum — a PDF with an unknown count must not
-        // fail the request outright — but the gap itself must not be silent.
-        const unknownPageCountFiles = pdfFiles.filter((f) => f.pageCount === null || f.pageCount === undefined);
-        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 (unknownPageCountFiles.length > 0) {
-            // Filenames are caller-controlled and may be full paths carrying
-            // PII/internal directory segments — log only the basename.
-            const unknownFileNames = unknownPageCountFiles
-                .map((f) => (f.filename ? basename(f.filename) : "<unnamed file>"))
-                .join(", ");
-            logger.warn(`[PDF] Aggregate page-limit check across ${pdfFiles.length} PDFs could only be ` +
-                `partially verified: ${unknownPageCountFiles.length} file(s) have an unknown ` +
-                `page count (${unknownFileNames}), so the known total (${totalPages}) may ` +
-                `undercount the true combined page count.`);
-        }
-        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}.`);
-        }
-    }
+    // Counts here come from FileDetector's detection, so they are authoritative.
+    await enforceAggregatePdfLimits(pdfFiles, provider, {
+        trustSuppliedPageCounts: true,
+    });
     return pdfFiles;
 }
 /**
@@ -1390,6 +1459,12 @@ async function convertContentToProviderFormat(content, provider, _model, pdfOpti
         password: pdfOptions?.password,
         maxCanvasPixels: pdfOptions?.maxCanvasPixels,
     }));
+    // #309: same aggregate ceiling as `input.pdfFiles`. Without this, moving an
+    // over-limit payload from `input.pdfFiles` to `input.content` skipped the
+    // check entirely and the request went straight to the provider.
+    await enforceAggregatePdfLimits(pdfFiles, provider, {
+        trustSuppliedPageCounts: false,
+    });
     return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, _model);
 }
 /**

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

@@ -18,6 +18,17 @@ export declare class PDFProcessor {
      */
     static supportsNativePDF(provider: string): boolean;
     static getProviderConfig(provider: string): PDFProviderConfig | null;
+    /**
+     * Best-effort page count for a PDF whose count the caller did not supply
+     * (#309). Mirrors what `process()` derives for the `input.pdfFiles` path:
+     * the accurate pdfjs count when the document parses, otherwise the header
+     * regex estimate. Returns null when neither can determine a count.
+     *
+     * Exists so the aggregate page-limit guard can enforce against PDFs handed
+     * in via `input.content`, where `metadata.pages` is optional and routinely
+     * omitted — without it, an absent count silently sums as zero.
+     */
+    static resolvePageCount(buffer: Buffer): Promise<number | null>;
     private static isValidPDF;
     private static extractBasicMetadata;
     /**