@juspay/neurolink 10.10.7 → 10.10.9

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

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

@@ -225,11 +225,26 @@ export type StreamOptions = {
         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;
     };
     /**

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",