@juspay/neurolink 10.10.6 → 10.10.8

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/providers/googleAiStudio/client.d.ts

@@ -2,37 +2,6 @@ import { type AIProviderName } from "../../constants/enums.js";
 import { BaseProvider } from "../../core/baseProvider.js";
 import type { ZodUnknownSchema, EnhancedGenerateResult, TextGenerationOptions, StreamOptions, StreamResult } from "../../types/index.js";
 import type { LanguageModel, Schema } from "../../types/index.js";
-/**
- * Google AI Studio provider implementation using BaseProvider
- * Migrated from original GoogleAIStudio class to new factory pattern
- *
- * @important Structured Output Limitation
- * Google Gemini models cannot combine function calling (tools) with structured
- * output (JSON schema). When using schemas with output.format: "json", you MUST
- * set disableTools: true.
- *
- * Error without disableTools:
- * "Function calling with a response mime type: 'application/json' is unsupported"
- *
- * This is a Google API limitation documented at:
- * https://ai.google.dev/gemini-api/docs/function-calling
- *
- * @example
- * ```typescript
- * // ✅ Correct usage with schemas
- * const provider = new GoogleAIStudioProvider("gemini-2.5-flash");
- * const result = await provider.generate({
- *   input: { text: "Analyze data" },
- *   schema: MySchema,
- *   output: { format: "json" },
- *   disableTools: true  // Required
- * });
- * ```
- *
- * @note Gemini 3 Pro Preview (November 2025) will support combining tools + schemas
- * @note "Too many states for serving" errors can occur with complex schemas + tools.
- *       Solution: Simplify schema or use disableTools: true
- */
 export declare class GoogleAIStudioProvider extends BaseProvider {
     private credentials?;
     constructor(modelName?: string, sdk?: unknown, credentials?: {

package/dist/providers/googleAiStudio/client.js

@@ -6,12 +6,14 @@ import { ATTR, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "
 import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../../types/index.js";
 import { ERROR_CODES, NeuroLinkError } from "../../utils/errorHandling.js";
 import { logger } from "../../utils/logger.js";
+import { GEMINI_ELISION_NOTE, planGeminiLoopReclaim, previewGeminiToolResponseText, } from "../../context/geminiLoopGuard.js";
+import { getAvailableInputTokens, getContextWindowSize, } from "../../constants/contextWindows.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../../utils/timeout.js";
 import { withTimeout } from "../../utils/async/index.js";
 import { estimateTokens } from "../../utils/tokenEstimation.js";
 import { transformToolExecutions } from "../../utils/transformationUtils.js";
 import { resolveToolExecutionRecords } from "../../core/toolExecutionRecorder.js";
-import { buildGeminiResponseSchema, buildNativeConfig, buildNativeToolDeclarations, collectStreamChunks, collectStreamChunksIncremental, computeMaxSteps, createTextChannel, buildUserPartsWithMultimodal, executeNativeToolCalls, extractTextFromParts, extractThoughtSignature, handleMaxStepsTermination, prependConversationMessages, pushModelResponseToHistory, refreshNativeToolDeclarations, DedupExecuteMap, } from "../googleNativeGemini3/index.js";
+import { buildGeminiResponseSchema, buildNativeConfig, buildNativeToolDeclarations, collectStreamChunks, collectStreamChunksIncremental, computeMaxSteps, createContextGuard, createTextChannel, buildUserPartsWithMultimodal, executeNativeToolCalls, extractTextFromParts, extractThoughtSignature, handleMaxStepsTermination, prependConversationMessages, pushModelResponseToHistory, refreshNativeToolDeclarations, DedupExecuteMap, } from "../googleNativeGemini3/index.js";
 import { createProxyFetch } from "../../proxy/proxyFetch.js";
 // Google AI Live API types now imported from ../types/providerSpecific.js
 // Import proper types for multimodal message handling
@@ -69,6 +71,74 @@ async function createGoogleGenAIClient(apiKey) {
  * @note "Too many states for serving" errors can occur with complex schemas + tools.
  *       Solution: Simplify schema or use disableTools: true
  */
+/**
+ * Reclaim context from an AI Studio loop history IN PLACE.
+ *
+ * This loop had NO in-turn guard at all — it appended a model turn plus a tool
+ * turn every step with nothing bounding growth, so a long agentic run walked
+ * into a provider "context length exceeded" and lost every completed step.
+ * Shares its reclaim policy with the other provider loops via loopGuardCore.
+ *
+ * Returns true when something was reclaimed.
+ */
+function reclaimAiStudioContext(contents, modelName, observedPromptTokens) {
+    const plan = planGeminiLoopReclaim({
+        contents,
+        availableInputTokens: getAvailableInputTokens("googleAiStudio", modelName),
+        provider: "googleAiStudio",
+        ...(observedPromptTokens ? { 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) => {
+                    const record = part;
+                    if (!record.functionResponse) {
+                        return part;
+                    }
+                    const text = JSON.stringify(record.functionResponse.response) ?? "";
+                    if (text.length <= 2048) {
+                        return part;
+                    }
+                    return {
+                        functionResponse: {
+                            name: record.functionResponse.name,
+                            response: { result: previewGeminiToolResponseText(text) },
+                        },
+                    };
+                }),
+            });
+            continue;
+        }
+        rebuilt.push(content);
+    }
+    if (dropSet.size > 0) {
+        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;
+}
 export class GoogleAIStudioProvider extends BaseProvider {
     credentials;
     constructor(modelName, sdk, credentials) {
@@ -595,9 +665,27 @@ export class GoogleAIStudioProvider extends BaseProvider {
                     let step = 0;
                     let completedWithFinalAnswer = false;
                     const failedTools = new Map();
+                    // Cheap trigger for the in-turn reclaim, mirroring the Vertex twin.
+                    // Planning serializes the WHOLE accumulated history to estimate it,
+                    // so running it unconditionally charges that once per step for the
+                    // life of the turn; the guard tracks real prompt counts plus
+                    // measured growth instead, and it supplies the observed count that
+                    // calibrates the planner's char estimate.
+                    const contextGuard = createContextGuard(getContextWindowSize("googleAiStudio", modelName));
                     try {
                         // Agentic loop for tool calling
                         while (step < maxSteps) {
+                            // In-turn context guard: this loop appends a model turn plus a
+                            // tool turn every step with nothing bounding growth. No-op
+                            // while the request still fits, so a loop that fits never pays
+                            // a cache invalidation. Step 0 still plans unconditionally —
+                            // the guard has no usage to go on yet, and the incoming history
+                            // can already be oversized before the first call.
+                            if (step === 0 || contextGuard.shouldStop()) {
+                                if (reclaimAiStudioContext(currentContents, modelName, contextGuard.projectedNextPromptTokens)) {
+                                    contextGuard.resetAfterReclaim();
+                                }
+                            }
                             if (composedSignal?.aborted) {
                                 throw composedSignal.reason instanceof Error
                                     ? composedSignal.reason
@@ -629,6 +717,10 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                 totalOutputTokens += chunkResult.outputTokens;
                                 totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                                 totalReasoningTokens += chunkResult.reasoningTokens ?? 0;
+                                // `inputTokens` is this step's promptTokenCount — the FULL
+                                // prompt size for the request just made, which is what the
+                                // guard projects the next request from.
+                                contextGuard.noteUsage(chunkResult.inputTokens, chunkResult.outputTokens);
                                 const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                                 // If no function calls, this was the final step — channel
                                 // already received all text parts incrementally.
@@ -691,6 +783,14 @@ export class GoogleAIStudioProvider extends BaseProvider {
                                     role: "user",
                                     parts: functionResponses,
                                 });
+                                // Project this step's growth: the appended tool results ride
+                                // the next prompt, which the provider has not reported on yet.
+                                try {
+                                    contextGuard.noteAppendedChars(JSON.stringify(functionResponses).length);
+                                }
+                                catch {
+                                    /* estimation is best-effort — never break the loop */
+                                }
                             }
                             catch (error) {
                                 logger.error("[GoogleAIStudio] Native SDK error", error);
@@ -877,8 +977,16 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 const toolExecutions = [];
                 let step = 0;
                 const failedTools = new Map();
+                // Cheap reclaim trigger — see the stream twin.
+                const contextGuard = createContextGuard(getContextWindowSize("googleAiStudio", modelName));
                 // Agentic loop for tool calling
                 while (step < maxSteps) {
+                    // In-turn context guard — see the stream twin.
+                    if (step === 0 || contextGuard.shouldStop()) {
+                        if (reclaimAiStudioContext(currentContents, modelName, contextGuard.projectedNextPromptTokens)) {
+                            contextGuard.resetAfterReclaim();
+                        }
+                    }
                     if (composedSignal?.aborted) {
                         throw composedSignal.reason instanceof Error
                             ? composedSignal.reason
@@ -904,6 +1012,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         totalOutputTokens += chunkResult.outputTokens;
                         totalCacheReadTokens += chunkResult.cacheReadTokens ?? 0;
                         totalReasoningTokens += chunkResult.reasoningTokens ?? 0;
+                        contextGuard.noteUsage(chunkResult.inputTokens, chunkResult.outputTokens);
                         const stepText = extractTextFromParts(chunkResult.rawResponseParts);
                         // If no function calls, we're done
                         if (chunkResult.stepFunctionCalls.length === 0) {
@@ -961,6 +1070,14 @@ export class GoogleAIStudioProvider extends BaseProvider {
                             role: "user",
                             parts: functionResponses,
                         });
+                        // Project this step's growth: the appended tool results ride
+                        // the next prompt, which the provider has not reported on yet.
+                        try {
+                            contextGuard.noteAppendedChars(JSON.stringify(functionResponses).length);
+                        }
+                        catch {
+                            /* estimation is best-effort — never break the loop */
+                        }
                     }
                     catch (error) {
                         logger.error("[GoogleAIStudio] Native SDK generate error", error);

package/dist/providers/googleNativeGemini3/utils.d.ts

@@ -385,6 +385,15 @@ export declare function createContextGuard(contextWindowTokens: number, threshol
      * results, nudge text) using the ~4 chars/token heuristic.
      */
     noteAppendedChars(chars: number): void;
+    /**
+     * Clear the projection after the caller has reclaimed context.
+     *
+     * The observed prompt size reflects the pre-reclaim conversation, so
+     * leaving it in place would keep `shouldStop()` true forever and defeat
+     * the reclaim. Resetting to the fail-open state means the guard stays
+     * quiet until the next real usage report re-establishes the truth.
+     */
+    resetAfterReclaim(): void;
     /** True when issuing another model call risks crossing the threshold. */
     shouldStop(): boolean;
 };

package/dist/providers/googleNativeGemini3/utils.js

@@ -1229,6 +1229,18 @@ export function createContextGuard(contextWindowTokens, thresholdRatio = DEFAULT
                 projectedGrowthTokens += Math.ceil(chars / 4);
             }
         },
+        /**
+         * Clear the projection after the caller has reclaimed context.
+         *
+         * The observed prompt size reflects the pre-reclaim conversation, so
+         * leaving it in place would keep `shouldStop()` true forever and defeat
+         * the reclaim. Resetting to the fail-open state means the guard stays
+         * quiet until the next real usage report re-establishes the truth.
+         */
+        resetAfterReclaim() {
+            observedPromptTokens = 0;
+            projectedGrowthTokens = 0;
+        },
         /** True when issuing another model call risks crossing the threshold. */
         shouldStop() {
             return (observedPromptTokens > 0 &&

package/dist/providers/googleVertex/client.d.ts

@@ -51,51 +51,6 @@ export declare function stripAdditionalPropertiesDeep(schema: Record<string, unk
  * @returns The region string to pass to the @google/genai client.
  */
 export declare const resolveVertexLocation: (modelName: string | undefined, configuredLocation?: string) => string;
-/**
- * Google Vertex AI Provider v2 - BaseProvider Implementation
- *
- * Features:
- * - Extends BaseProvider for shared functionality
- * - Preserves existing Google Cloud authentication
- * - Maintains Anthropic model support via dynamic imports
- * - Fresh model creation for each request
- * - Enhanced error handling with setup guidance
- * - Tool registration and context management
- *
- * @important Tools + Schema Support (Fixed)
- * Gemini models on Vertex AI now support combining function calling (tools) with
- * structured output (JSON schema) simultaneously. The fix works by NOT setting
- * `responseMimeType: "application/json"` when tools are present, which was
- * causing the Google API error.
- *
- * The `responseSchema` is still set to guide the output structure, allowing
- * tools to execute AND the final output to follow the schema format.
- *
- * @example Gemini models with tools + schemas
- * ```typescript
- * const provider = new GoogleVertexProvider("gemini-2.5-flash");
- * const result = await provider.generate({
- *   input: { text: "Analyze data using tools" },
- *   schema: MySchema,
- *   output: { format: "json" },
- *   // No need for disableTools: true anymore!
- * });
- * ```
- *
- * @example Claude models (always supported both)
- * ```typescript
- * const provider = new GoogleVertexProvider("claude-3-5-sonnet-20241022");
- * const result = await provider.generate({
- *   input: { text: "Analyze data" },
- *   schema: MySchema,
- *   output: { format: "json" }
- * });
- * ```
- *
- * @note "Too many states for serving" errors can still occur with very complex schemas + tools.
- *       Solution: Simplify schema or reduce number of tools if this occurs.
- * @see https://cloud.google.com/vertex-ai/docs/generative-ai/learn/models
- */
 export declare class GoogleVertexProvider extends BaseProvider {
     private projectId;
     private location;