@juspay/neurolink 10.10.7 → 10.10.9

package/dist/lib/utils/messageBuilder.js

@@ -1,10 +1,10 @@
 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";
 import { getAvailableInputTokens } from "../constants/contextWindows.js";
+import { PDF_LIMITS } from "../core/constants.js";
 import { enforceAggregateFileBudget, FILE_READ_BUDGET_PERCENT, } from "../context/fileTokenBudget.js";
 import { isCSVContent, SIZE_TIER_THRESHOLDS } from "../types/index.js";
 import { tracers, ATTR, withSpan } from "../telemetry/index.js";
@@ -809,6 +809,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 +839,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 +897,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 +1044,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.
  */
@@ -1050,6 +1151,10 @@ async function processExplicitPdfFiles(options, maxSize, provider) {
                     // #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,
+                    // #297: render scale / page ceiling, so the lowered default is
+                    // actually reachable and callers can trade sharpness for memory.
+                    scale: options.pdfOptions?.scale,
+                    maxPages: options.pdfOptions?.maxPages,
                 });
                 logger.info(`[PDF] ✅ Queued for multimodal: ${filename} (${result.metadata?.estimatedPages ?? "unknown"} pages)`);
             }
@@ -1059,41 +1164,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;
 }
 /**
@@ -1389,7 +1463,15 @@ async function convertContentToProviderFormat(content, provider, _model, pdfOpti
         // guard as the `input.pdfFiles` path (see `processExplicitPdfFiles`).
         password: pdfOptions?.password,
         maxCanvasPixels: pdfOptions?.maxCanvasPixels,
+        scale: pdfOptions?.scale,
+        maxPages: pdfOptions?.maxPages,
     }));
+    // #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);
 }
 /**
@@ -1734,7 +1816,10 @@ async function convertSimpleImagesToProviderFormat(text, images, provider, _mode
 /**
  * Convert multimodal content (images + PDFs) to provider format
  */
-async function convertMultimodalToProviderFormat(text, images, pdfFiles, provider, model) {
+async function convertMultimodalToProviderFormat(text, images, 
+// The canonical entry shape (#309) rather than a fourth copy of it inline —
+// which is what let the render knobs stop short of this function.
+pdfFiles, provider, model) {
     const content = [
         { type: "text", text },
     ];
@@ -1768,14 +1853,41 @@ async function convertMultimodalToProviderFormat(text, images, pdfFiles, provide
         logger.info(`[PDF→Image] Provider ${provider} doesn't support native PDF. Converting ${pdfFiles.length} PDF(s) to images...`);
         for (const pdf of pdfFiles) {
             try {
+                const effectiveMaxPages = pdf.maxPages ?? PDF_LIMITS.DEFAULT_MAX_PAGES;
                 const conversionResult = await PDFImageConverter.convertToImages(pdf.buffer, {
-                    scale: 2.0, // High quality for OCR/analysis
-                    maxPages: 20, // Limit pages to prevent token overflow
+                    // #297: this is the only PDF→image call the product actually makes,
+                    // and it used to hardcode scale 2.0 — silently overriding the
+                    // lowered PDF_LIMITS.DEFAULT_SCALE and keeping the memory cost the
+                    // issue reports (a 100-page render at 2.0 is ~776MB; 1.5 is ~44%
+                    // fewer pixels per page). Callers can raise it back per request.
+                    scale: pdf.scale ?? PDF_LIMITS.DEFAULT_SCALE,
+                    // Page ceiling guards token overflow; also now caller-adjustable
+                    // rather than a constant nothing could reach.
+                    maxPages: effectiveMaxPages,
                     ...(pdf.password ? { password: pdf.password } : {}), // #258
                     ...(pdf.maxCanvasPixels
                         ? { maxCanvasPixels: pdf.maxCanvasPixels }
                         : {}), // #260
                 });
+                // The renderer stops at maxPages, so a longer document is silently
+                // truncated — say so rather than letting the model answer from a
+                // partial document as though it had the whole thing.
+                //
+                // Keyed on the cap being reached, not on pdf.pageCount: that field is
+                // null whenever `input.content` omits `metadata.pages`, which is the
+                // common case, so a page-count comparison would simply never fire
+                // there. Reaching the cap is also unambiguous — a short count caused by
+                // per-page render failures (#294 isolates those into `errors`) would
+                // otherwise be misreported as a maxPages truncation.
+                if (conversionResult.pageCount >= effectiveMaxPages) {
+                    logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)} hit the ${effectiveMaxPages}-page ` +
+                        `conversion limit. Any pages beyond that were not sent — the model may be ` +
+                        `answering from a partial document. Raise pdfOptions.maxPages or split the file.`);
+                }
+                if (conversionResult.errors && conversionResult.errors.length > 0) {
+                    logger.warn(`[PDF→Image] ${safeBasename(pdf.filename)}: ${conversionResult.errors.length} page(s) ` +
+                        `failed to render and were omitted (page ${conversionResult.errors.map((e) => e.page).join(", ")}).`);
+                }
                 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)
                 conversionResult.images.forEach((base64Image, pageIndex) => {

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

@@ -58,6 +58,8 @@ export declare function buildMultimodalOptions(options: StreamOptions, providerN
     pdfOptions: {
         password?: string;
         maxCanvasPixels?: number;
+        scale?: number;
+        maxPages?: number;
     } | undefined;
     systemPrompt: string | undefined;
     conversationHistory: import("../types/conversation.js").ChatMessage[] | undefined;

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;
     /**

package/dist/lib/utils/pdfProcessor.js

@@ -212,6 +212,23 @@ export class PDFProcessor {
     static getProviderConfig(provider) {
         return PDF_PROVIDER_CONFIGS[provider] || 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 async resolvePageCount(buffer) {
+        const accurate = await PDFProcessor.getAccuratePageCount(buffer);
+        if (accurate !== null) {
+            return accurate;
+        }
+        return PDFProcessor.extractBasicMetadata(buffer).estimatedPages;
+    }
     static isValidPDF(buffer) {
         if (buffer.length < 5) {
             return false;
@@ -360,6 +377,7 @@ export class PDFProcessor {
             format,
             scale,
             maxCanvasPixels,
+            maxPages,
         });
         logger.debug("[PDF→Image] ✅ PDF validation passed", {
             bufferSize: pdfBuffer.length,
@@ -518,6 +536,14 @@ export class PDFProcessor {
         if (!Number.isFinite(opts.maxCanvasPixels) || opts.maxCanvasPixels <= 0) {
             throw new Error(`Invalid maxCanvasPixels: ${opts.maxCanvasPixels}. Must be a finite number greater than 0.`);
         }
+        // #297: maxPages became caller-controlled, and an unvalidated 0/-1/NaN
+        // silently converts nothing, surfacing later as a misleading
+        // "PDF has 0 pages" from deep inside the renderer. Reject it here where
+        // the message can still name the offending option.
+        if (opts.maxPages !== undefined &&
+            (!Number.isInteger(opts.maxPages) || opts.maxPages < 1)) {
+            throw new Error(`Invalid maxPages: ${opts.maxPages}. Must be a whole number of at least 1.`);
+        }
         if (!pdfBuffer || pdfBuffer.length < 5) {
             throw new Error("Invalid PDF: Buffer is too small or empty. " +
                 "A valid PDF must be at least 5 bytes (PDF header).");
@@ -553,6 +579,7 @@ export class PDFProcessor {
             format,
             scale,
             maxCanvasPixels,
+            maxPages,
         });
         const pdfToImgModule = await import("pdf-to-img");
         const pdf = pdfToImgModule.pdf;

package/dist/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/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/skills/skillsManager.js

@@ -87,7 +87,14 @@ export class SkillsManager {
         // name-find would resolve non-deterministically to the stale deprecated one
         // across store backends. Fall back to any match only when no active skill
         // carries the name.
-        const entry = index.find((item) => item.name === idOrName && (item.status ?? "active") === "active") ?? index.find((item) => item.name === idOrName);
+        //
+        // Matched case-insensitively to agree with assertNameAvailable, which
+        // enforces uniqueness that way: names differing only in case cannot
+        // coexist, so a case-sensitive lookup could only fail to find a skill that
+        // is definitively there (`get("DEPLOY")` returned null for "deploy").
+        const wanted = idOrName.toLowerCase();
+        const entry = index.find((item) => item.name.toLowerCase() === wanted &&
+            (item.status ?? "active") === "active") ?? index.find((item) => item.name.toLowerCase() === wanted);
         return entry ? this.store.get(entry.id) : null;
     }
     /**
@@ -237,11 +244,23 @@ export class SkillsManager {
     }
     async assertNameAvailable(name, excludeId) {
         const index = await this.getIndex(true);
-        const clash = index.find((item) => item.id !== excludeId &&
-            item.name.toLowerCase() === name.toLowerCase() &&
-            (item.status ?? "active") === "active");
+        // Deliberately NOT filtered to active (#1139). Soft-delete only flips
+        // status to "deprecated" — the entry stays in the index, so allowing a new
+        // skill to take the name left two entries sharing it. Every name-based
+        // lookup (CLI `skills show/delete <name>`, the skill_update/skill_delete
+        // tools, the `:id`-or-name REST routes) then had to guess which one the
+        // caller meant, and iteration order differs across store backends.
+        //
+        // A deprecated skill's name therefore stays reserved. Reusing it requires
+        // hard-deleting the old skill first, which is the explicit choice the
+        // ambiguity demands.
+        const clash = index.find((item) => item.id !== excludeId && item.name.toLowerCase() === name.toLowerCase());
         if (clash) {
-            throw new Error(`A skill named "${name}" already exists`);
+            const suffix = (clash.status ?? "active") === "active"
+                ? ""
+                : ` (that name belongs to a deprecated skill, id ${clash.id}; ` +
+                    `remove it before reusing the name)`;
+            throw new Error(`A skill named "${name}" already exists${suffix}`);
         }
     }
 }

package/dist/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,31 @@ 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;
+    /** Render scale for the image fallback (#297). */
+    scale?: number;
+    /** Max pages converted by the image fallback (#297). */
+    maxPages?: number;
+};
 /** Result of PDF to image conversion. */
 export type PDFImageConversionResult = {
     /** Array of base64-encoded PNG images (one per successfully converted page) */

package/dist/types/generate.d.ts

@@ -133,11 +133,26 @@ export type GenerateOptions = {
         password?: string;
         /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
         maxCanvasPixels?: number;
+        /**
+         * Render scale for the image fallback used by providers without native PDF
+         * support (#297). Higher is sharper but costs roughly the square in memory
+         * and tokens. Range 0.1-10; defaults to PDF_LIMITS.DEFAULT_SCALE (1.5).
+         */
+        scale?: number;
+        /**
+         * Max pages converted by the image fallback (#297). Pages beyond this are
+         * not sent to the model at all. Defaults to PDF_LIMITS.DEFAULT_MAX_PAGES (20).
+         */
+        maxPages?: 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;
     };
     /**
@@ -1261,6 +1276,10 @@ export type TextGenerationOptions = {
         password?: string;
         /** Max rendered-canvas pixels per page (#260 memory guard); oversized pages auto-downscale. */
         maxCanvasPixels?: number;
+        /** Render scale for the image fallback (#297); defaults to PDF_LIMITS.DEFAULT_SCALE. */
+        scale?: number;
+        /** Max pages converted by the image fallback (#297); defaults to PDF_LIMITS.DEFAULT_MAX_PAGES. */
+        maxPages?: number;
     };
     enableSummarization?: boolean;
     /**