@juspay/neurolink 10.10.6 → 10.10.8

package/dist/providers/googleVertex/client.js

@@ -16,6 +16,8 @@ import { applyVertexAnthropicCacheBreakpoints } from "../../utils/anthropicCache
 import { FileDetector } from "../../utils/fileDetector.js";
 import { mergeMediaFileAliases, processUnifiedFilesArray, } from "../../utils/messageBuilder.js";
 import { logger } from "../../utils/logger.js";
+import { GEMINI_ELISION_NOTE, planGeminiLoopReclaim, previewGeminiToolResponseText, } from "../../context/geminiLoopGuard.js";
+import { ANTHROPIC_ELISION_NOTE, planAnthropicLoopReclaim, previewAnthropicToolResultText, } from "../../context/anthropicLoopGuard.js";
 import { hasRestrictedOutputLimit, RESTRICTED_OUTPUT_TOKEN_LIMIT, toVertexAnthropicModelId, } from "../../utils/modelDetection.js";
 import { detectImageMimeType } from "../../utils/imageDetection.js";
 import { resolveClaudeMaxTokens } from "../../utils/tokenLimits.js";
@@ -25,7 +27,7 @@ import { createNativeThinkingConfig } from "../../utils/thinkingConfig.js";
 import { TimeoutError, raceWithAbort, withTimeout, } from "../../utils/async/index.js";
 import { parseTimeout } from "../../utils/timeout.js";
 import { appendStepText, buildAbortedTurnMessage, buildContextCapMessage, buildToolLoopCapMessage, buildTurnStalledMessage, buildTurnTimeoutMessage, buildWrapupNudgeText, createContextGuard, createTextChannel, createTurnClock, extractThoughtSignature, isAbortError, mapGeminiFinishReason, prependConversationMessages, resolveTurnStopReason, DedupExecuteMap, } from "../googleNativeGemini3/index.js";
-import { getContextWindowSize } from "../../constants/contextWindows.js";
+import { getAvailableInputTokens, getContextWindowSize, } from "../../constants/contextWindows.js";
 import { resolveLiveTool } from "../../tools/toolDiscovery.js";
 import { ATTR, LANGFUSE_ATTR, spanJsonAttribute, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "../../telemetry/index.js";
 import { SpanKind, SpanStatusCode, context as otelContext, trace as otelTrace, } from "@opentelemetry/api";
@@ -587,6 +589,148 @@ const isAnthropicModel = (modelName) => {
  *       Solution: Simplify schema or reduce number of tools if this occurs.
  * @see https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models
  */
+/** Byte budget above which an old tool response is previewed, not kept whole. */
+const TOOL_RESPONSE_PREVIEW_BYTES = 2048;
+/**
+ * Reclaim context from a Gemini-shaped loop history IN PLACE.
+ *
+ * Returns true when something was actually reclaimed, which tells the caller
+ * it is safe to continue the loop instead of stopping. Mutates `contents` so
+ * the caller's array identity (captured by the request builder) stays valid.
+ */
+function reclaimVertexLoopContext(contents, modelName, observedPromptTokens) {
+    const plan = planGeminiLoopReclaim({
+        contents,
+        // The usable INPUT budget, not the whole window: the window has to hold the
+        // model's output too, and the AI Studio twin already reclaims against this
+        // same definition.
+        availableInputTokens: getAvailableInputTokens("vertex", modelName),
+        provider: "vertex",
+        observedPromptTokens,
+    });
+    if (!plan) {
+        return false;
+    }
+    const dropSet = new Set(plan.drop);
+    const truncateSet = new Set(plan.truncate);
+    const rebuilt = [];
+    for (let i = 0; i < contents.length; i++) {
+        if (dropSet.has(i)) {
+            continue;
+        }
+        const content = contents[i];
+        if (truncateSet.has(i) && Array.isArray(content.parts)) {
+            rebuilt.push({
+                ...content,
+                parts: content.parts.map((part) => {
+                    if (!("functionResponse" in part)) {
+                        return part;
+                    }
+                    const fn = part.functionResponse;
+                    const text = JSON.stringify(fn.response) ?? "";
+                    if (text.length <= TOOL_RESPONSE_PREVIEW_BYTES) {
+                        return part;
+                    }
+                    // Rebuilt rather than cast: `functionResponse` requires `name`, and
+                    // Critical Rule 14 forbids casting through `unknown` to paper over it.
+                    return {
+                        functionResponse: {
+                            name: fn.name,
+                            response: { result: previewGeminiToolResponseText(text) },
+                        },
+                    };
+                }),
+            });
+            continue;
+        }
+        rebuilt.push(content);
+    }
+    if (dropSet.size > 0) {
+        // Gemini requires the history to start with a user turn; the note is
+        // inserted before the first surviving tool turn, never at the end where a
+        // "history was removed" cue would follow the content it refers to.
+        let noteIndex = rebuilt.findIndex((c) => Array.isArray(c.parts) &&
+            c.parts.some((part) => !!part.functionCall ||
+                !!part.functionResponse));
+        if (noteIndex < 0) {
+            noteIndex = Math.min(1, rebuilt.length);
+        }
+        rebuilt.splice(noteIndex, 0, {
+            role: "user",
+            parts: [{ text: GEMINI_ELISION_NOTE }],
+        });
+    }
+    contents.length = 0;
+    contents.push(...rebuilt);
+    return true;
+}
+/**
+ * Reclaim context from a Vertex+Claude loop history IN PLACE.
+ *
+ * Same parity upgrade as the Gemini path, but this loop carries Anthropic
+ * content blocks, so it reuses the Anthropic adapter. Returns true when
+ * something was reclaimed and the loop may continue.
+ */
+function reclaimVertexAnthropicContext(messages, modelName, observedPromptTokens) {
+    const plan = planAnthropicLoopReclaim({
+        conversation: messages,
+        // Usable input budget, matching the Gemini twin above.
+        availableInputTokens: getAvailableInputTokens("vertex", modelName),
+        fixedOverheadTokens: 0,
+        provider: "vertex",
+        observedPromptTokens,
+        // This loop plans only when its context guard trips, so the count it hands
+        // over is the guard's projection for the request about to be sent, not a
+        // previous request's total. Without saying so the planner has no
+        // denominator, calibration stays pinned at 1, and the reclaim is inert:
+        // the guard fires on real tokens at the same ratio the planner tests its
+        // smaller char estimate against, so the plan never fires and the turn stops
+        // instead of continuing.
+        observedDescribesCurrentPayload: true,
+    });
+    if (!plan) {
+        return false;
+    }
+    const dropSet = new Set(plan.drop);
+    const truncateSet = new Set(plan.truncate);
+    const rebuilt = [];
+    for (let i = 0; i < messages.length; i++) {
+        if (dropSet.has(i)) {
+            continue;
+        }
+        const message = messages[i];
+        if (truncateSet.has(i) && Array.isArray(message.content)) {
+            rebuilt.push({
+                ...message,
+                content: message.content.map((block) => {
+                    if (block.type !== "tool_result") {
+                        return block;
+                    }
+                    const text = typeof block.content === "string"
+                        ? block.content
+                        : (JSON.stringify(block.content) ?? "");
+                    return { ...block, content: previewAnthropicToolResultText(text) };
+                }),
+            });
+            continue;
+        }
+        rebuilt.push(message);
+    }
+    if (dropSet.size > 0) {
+        let noteIndex = rebuilt.findIndex((m) => Array.isArray(m.content) &&
+            m.content.some((b) => b.type === "tool_use" || b.type === "tool_result"));
+        if (noteIndex < 0) {
+            noteIndex = Math.min(1, rebuilt.length);
+        }
+        rebuilt.splice(noteIndex, 0, {
+            role: "user",
+            content: [{ type: "text", text: ANTHROPIC_ELISION_NOTE }],
+        });
+    }
+    messages.length = 0;
+    messages.push(...rebuilt);
+    return true;
+}
 export class GoogleVertexProvider extends BaseProvider {
     projectId;
     location;
@@ -1574,11 +1718,22 @@ export class GoogleVertexProvider extends BaseProvider {
                 // conversation crosses the window threshold — synthesize from what
                 // we have instead of stepping into a provider rejection.
                 if (contextGuard.shouldStop()) {
-                    hitContextLimit = true;
-                    logger.warn(`[GoogleVertex] Gemini turn stopped by the context guard: ` +
-                        `projected prompt ~${contextGuard.projectedNextPromptTokens} tokens ` +
-                        `>= threshold ${contextGuard.thresholdTokens} (step ${step}) — synthesizing a final answer.`);
-                    break;
+                    // Parity upgrade: try to RECLAIM budget and keep going before
+                    // falling back to the historic stop-only behaviour. Ending the turn
+                    // early is safe but throws away work the model was mid-way through;
+                    // dropping the oldest complete tool exchanges usually buys enough
+                    // room to finish. Only when reclaiming changes nothing do we stop.
+                    const reclaimed = reclaimVertexLoopContext(currentContents, modelName, contextGuard.projectedNextPromptTokens);
+                    if (reclaimed) {
+                        contextGuard.resetAfterReclaim();
+                    }
+                    else {
+                        hitContextLimit = true;
+                        logger.warn(`[GoogleVertex] Gemini turn stopped by the context guard: ` +
+                            `projected prompt ~${contextGuard.projectedNextPromptTokens} tokens ` +
+                            `>= threshold ${contextGuard.thresholdTokens} (step ${step}) — synthesizing a final answer.`);
+                        break;
+                    }
                 }
                 step++;
                 turnClock.noteProgress();
@@ -2550,11 +2705,22 @@ export class GoogleVertexProvider extends BaseProvider {
                 // conversation crosses the window threshold — synthesize from what
                 // we have instead of stepping into a provider rejection.
                 if (contextGuard.shouldStop()) {
-                    hitContextLimit = true;
-                    logger.warn(`[GoogleVertex] Gemini turn stopped by the context guard: ` +
-                        `projected prompt ~${contextGuard.projectedNextPromptTokens} tokens ` +
-                        `>= threshold ${contextGuard.thresholdTokens} (step ${step}) — synthesizing a final answer.`);
-                    break;
+                    // Parity upgrade: try to RECLAIM budget and keep going before
+                    // falling back to the historic stop-only behaviour. Ending the turn
+                    // early is safe but throws away work the model was mid-way through;
+                    // dropping the oldest complete tool exchanges usually buys enough
+                    // room to finish. Only when reclaiming changes nothing do we stop.
+                    const reclaimed = reclaimVertexLoopContext(currentContents, modelName, contextGuard.projectedNextPromptTokens);
+                    if (reclaimed) {
+                        contextGuard.resetAfterReclaim();
+                    }
+                    else {
+                        hitContextLimit = true;
+                        logger.warn(`[GoogleVertex] Gemini turn stopped by the context guard: ` +
+                            `projected prompt ~${contextGuard.projectedNextPromptTokens} tokens ` +
+                            `>= threshold ${contextGuard.thresholdTokens} (step ${step}) — synthesizing a final answer.`);
+                        break;
+                    }
                 }
                 step++;
                 turnClock.noteProgress();
@@ -3671,11 +3837,19 @@ export class GoogleVertexProvider extends BaseProvider {
                     // Context guard: stop the tool loop before the accumulated
                     // conversation crosses the window threshold (see generate twin).
                     if (contextGuard.shouldStop()) {
-                        hitContextLimit = true;
-                        logger.warn(`[GoogleVertex] Anthropic stream turn stopped by the context guard: ` +
-                            `projected prompt ~${contextGuard.projectedNextPromptTokens} tokens ` +
-                            `>= threshold ${contextGuard.thresholdTokens} (step ${step}) — synthesizing a final answer.`);
-                        break;
+                        // Parity upgrade: reclaim and continue where possible; the
+                        // historic stop-only behaviour remains the fallback.
+                        const reclaimed = reclaimVertexAnthropicContext(currentMessages, modelName, contextGuard.projectedNextPromptTokens);
+                        if (reclaimed) {
+                            contextGuard.resetAfterReclaim();
+                        }
+                        else {
+                            hitContextLimit = true;
+                            logger.warn(`[GoogleVertex] Anthropic stream turn stopped by the context guard: ` +
+                                `projected prompt ~${contextGuard.projectedNextPromptTokens} tokens ` +
+                                `>= threshold ${contextGuard.thresholdTokens} (step ${step}) — synthesizing a final answer.`);
+                            break;
+                        }
                     }
                     step++;
                     turnClock.noteProgress();
@@ -4929,11 +5103,17 @@ export class GoogleVertexProvider extends BaseProvider {
             // this step's appended tool results/output) would cross the window
             // threshold — stop the tool loop and synthesize from what we have.
             if (contextGuard.shouldStop()) {
-                hitContextLimit = true;
-                logger.warn(`[GoogleVertex] Anthropic generate turn stopped by the context guard: ` +
-                    `projected prompt ~${contextGuard.projectedNextPromptTokens} tokens ` +
-                    `>= threshold ${contextGuard.thresholdTokens} (step ${step}) — synthesizing a final answer.`);
-                break;
+                const reclaimed = reclaimVertexAnthropicContext(currentMessages, modelName, contextGuard.projectedNextPromptTokens);
+                if (reclaimed) {
+                    contextGuard.resetAfterReclaim();
+                }
+                else {
+                    hitContextLimit = true;
+                    logger.warn(`[GoogleVertex] Anthropic generate turn stopped by the context guard: ` +
+                        `projected prompt ~${contextGuard.projectedNextPromptTokens} tokens ` +
+                        `>= threshold ${contextGuard.thresholdTokens} (step ${step}) — synthesizing a final answer.`);
+                    break;
+                }
             }
             step++;
             turnClock.noteProgress();

package/dist/types/context.d.ts

@@ -471,6 +471,15 @@ export type AnthropicGuardMessage = {
     role: "user" | "assistant" | "system";
     content: string | AnthropicGuardBlock[];
 };
+/**
+ * Structural view of one Gemini history entry, loose enough to accept both the
+ * native Vertex loop's `{ role, parts }` array and `@google/genai` contents
+ * without a cast at either call site.
+ */
+export type GeminiGuardContent = {
+    role: string;
+    parts: unknown[];
+};
 /** Tuning for {@link planLoopGuardReclaim}. */
 export type LoopGuardPolicy = {
     availableInputTokens: number;

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