@juspay/neurolink 9.15.0 → 9.16.0

package/dist/utils/logger.js

@@ -13,6 +13,22 @@
  * - Structured data support for complex objects
  * - Tabular data display
  */
+// OTel trace context for log correlation (optional — gracefully no-ops if OTel not initialized)
+let traceApi = null;
+let traceApiPromise = null;
+async function getTraceApi() {
+    if (!traceApiPromise) {
+        traceApiPromise = import("@opentelemetry/api")
+            .then((mod) => {
+            traceApi = mod;
+            return mod;
+        })
+            .catch(() => null);
+    }
+    return traceApiPromise;
+}
+// Eagerly kick off the import so the cached value is available for synchronous callers
+void getTraceApi();
 // Pre-computed uppercase log levels for performance optimization
 const UPPERCASE_LOG_LEVELS = {
     debug: "DEBUG",
@@ -95,6 +111,34 @@ class NeuroLinkLogger {
     getLogPrefix(timestamp, level) {
         return `[${timestamp}] [NEUROLINK:${UPPERCASE_LOG_LEVELS[level]}]`;
     }
+    /**
+     * Extracts current OTel trace context (trace_id, span_id) if available.
+     * Returns empty object if OTel is not initialized or no active span exists.
+     */
+    getTraceContext() {
+        if (!traceApi) {
+            return {};
+        }
+        try {
+            const span = traceApi.trace.getSpan(traceApi.context.active());
+            if (!span) {
+                return {};
+            }
+            const spanContext = span.spanContext();
+            if (!spanContext ||
+                spanContext.traceId === "00000000000000000000000000000000") {
+                return {};
+            }
+            return {
+                trace_id: spanContext.traceId,
+                span_id: spanContext.spanId,
+                trace_flags: String(spanContext.traceFlags),
+            };
+        }
+        catch {
+            return {};
+        }
+    }
     /**
      * Safely serialize data to fully expanded JSON string.
      * Handles circular references and non-serializable values.
@@ -163,11 +207,15 @@ class NeuroLinkLogger {
             warn: console.warn,
             error: console.error,
         }[level];
+        const traceCtx = this.getTraceContext();
+        const tracePrefix = traceCtx.trace_id
+            ? ` [trace_id=${traceCtx.trace_id} span_id=${traceCtx.span_id}]`
+            : "";
         if (data !== undefined && data !== null) {
-            logMethod(prefix, message, this.serializeData(data));
+            logMethod(prefix + tracePrefix, message, this.serializeData(data));
         }
         else {
-            logMethod(prefix, message);
+            logMethod(prefix + tracePrefix, message);
         }
     }
     /**

package/dist/utils/messageBuilder.js

@@ -436,56 +436,28 @@ function shouldUseStructuredOutput(options) {
 }
 /**
  * Log structural metadata about a composed message array without logging content.
- * Per-message breakdown is behind logger.debug() to avoid production spam.
+ * Only logs a compact summary (role counts, total chars, estimated tokens).
+ * Per-message breakdown is intentionally omitted to avoid log noise
+ * (~600 lines per retry cascade with many messages).
  */
 function logMessageComposition(messages, requestId) {
-    // Skip entirely if neither info nor debug is enabled
-    if (!logger.shouldLog("info")) {
+    if (!logger.shouldLog("debug")) {
         return;
     }
     const roles = {};
     let totalChars = 0;
     for (const msg of messages) {
-        // Avoid JSON.stringify on multimodal content for the info-level summary;
-        // accurate per-message breakdown (with sizes) is computed only when debug
-        // logging is active (see below).
         const chars = typeof msg.content === "string" ? msg.content.length : 0;
         roles[msg.role] = (roles[msg.role] || 0) + 1;
         totalChars += chars;
     }
-    logger.info("[MessageBuilder] Composed", {
+    logger.debug("[MessageBuilder] Composed", {
         requestId,
         totalMessages: messages.length,
         roles,
         totalChars,
         estimatedTokens: Math.ceil(totalChars / 4),
     });
-    if (logger.shouldLog("debug")) {
-        const breakdown = messages.map((msg, i) => {
-            let chars;
-            if (typeof msg.content === "string") {
-                chars = msg.content.length;
-            }
-            else {
-                try {
-                    chars = JSON.stringify(msg.content).length;
-                }
-                catch {
-                    chars = String(msg.content).length;
-                }
-            }
-            return {
-                index: i,
-                role: msg.role,
-                chars,
-                estimatedTokens: Math.ceil(chars / 4),
-            };
-        });
-        logger.debug("[MessageBuilder] Per-message breakdown", {
-            requestId,
-            breakdown,
-        });
-    }
 }
 /**
  * Build a properly formatted message array for AI providers
@@ -663,10 +635,11 @@ function enforceFileBudget(options, provider, model) {
         fileType: f.fileType,
     })), availableTokens);
     if (budgetResult.excluded.length > 0) {
-        const includedNames = new Set(budgetResult.included.map((f) => f.name));
+        const includedIndices = new Set(budgetResult.included.map((f) => {
+            return budgetFiles.findIndex((bf) => bf.name === f.name);
+        }));
         options.input.files = options.input.files.filter((_file, idx) => {
-            const entry = budgetFiles[idx];
-            return includedNames.has(entry.name);
+            return includedIndices.has(idx);
         });
         options.input.text =
             (options.input.text || "") + "\n\n" + budgetResult.notices.join("\n");
@@ -1071,12 +1044,19 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
     // Add conversation history if available
     const hasConversationHistory = options.conversationHistory && options.conversationHistory.length > 0;
     if (hasConversationHistory && options.conversationHistory) {
-        options.conversationHistory.forEach((msg) => {
-            messages.push({
-                role: msg.role,
-                content: msg.content,
-            });
-        });
+        for (const msg of options.conversationHistory) {
+            // Filter out tool_call and tool_result roles — only user/assistant/system are valid for AI providers
+            if (msg.role === "user" ||
+                msg.role === "assistant" ||
+                msg.role === "system") {
+                const providerOptions = msg.providerOptions;
+                messages.push({
+                    role: msg.role,
+                    content: msg.content,
+                    ...(providerOptions && { providerOptions }),
+                });
+            }
+        }
     }
     // Handle multimodal content
     try {

package/dist/utils/modelDetection.js

@@ -11,7 +11,7 @@ export function isGemini3Model(modelName) {
     if (!isValidModelName(modelName)) {
         return false;
     }
-    return /^gemini-3(-.*)?$/i.test(modelName);
+    return /^gemini-3(\.\d+)?(-.*)?$/i.test(modelName);
 }
 export function isGemini25Model(modelName) {
     if (!isValidModelName(modelName)) {
@@ -46,10 +46,10 @@ export function getMaxThinkingBudgetTokens(modelName) {
     if (!isValidModelName(modelName)) {
         return 10000;
     }
-    if (/^gemini-3-pro/i.test(modelName)) {
+    if (/^gemini-3(\.\d+)?-pro/i.test(modelName)) {
         return 100000;
     }
-    if (/^gemini-3-flash/i.test(modelName)) {
+    if (/^gemini-3(\.\d+)?-flash/i.test(modelName)) {
         return 50000;
     }
     if (/^gemini-2\.5/i.test(modelName)) {

package/dist/utils/providerRetry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Provider-level retry utility for AI SDK calls (NL11)
+ *
+ * The Vercel AI SDK's `generateText()` and `streamText()` have built-in retry
+ * logic (`_retryWithExponentialBackoff()` with default `maxRetries: 2`) that
+ * retries on HTTP 429/500/503. These retries are completely invisible to OTel
+ * because they happen inside the AI SDK.
+ *
+ * This module provides an instrumented retry wrapper that:
+ * 1. Disables the AI SDK's internal retries (via `maxRetries: 0`)
+ * 2. Implements our own retry loop with full OTel span events
+ * 3. Records retry attempts, delays, status codes, and total attempt count
+ *
+ * @module utils/providerRetry
+ */
+import { type Span } from "@opentelemetry/api";
+/** Maximum number of retry attempts after the initial call (total = 1 + MAX_PROVIDER_RETRIES). */
+export declare const MAX_PROVIDER_RETRIES = 2;
+/** Base delay in ms for exponential backoff between retries. */
+export declare const BASE_RETRY_DELAY_MS = 1000;
+/**
+ * Check whether an error thrown by the AI SDK is retryable.
+ *
+ * Uses `APICallError.isInstance()` for proper type-safe detection (the class
+ * uses a branded symbol marker, so `instanceof` doesn't work across package
+ * boundaries). Falls back to duck-typing for non-APICallError cases.
+ */
+export declare function isRetryableProviderError(error: unknown): boolean;
+/**
+ * Extract the HTTP status code from an AI SDK error, if available.
+ */
+export declare function getErrorStatusCode(error: unknown): number | undefined;
+/**
+ * Execute a provider call with instrumented retry logic.
+ *
+ * @param operation  - The async operation to execute (should already use `maxRetries: 0`)
+ * @param span       - The OTel span to annotate with retry events and attributes
+ * @param label      - A human-readable label for log messages (e.g. "generateText", "streamText")
+ * @returns The result of the operation
+ */
+export declare function withProviderRetry<T>(operation: () => Promise<T>, span: Span, label: string): Promise<T>;

package/dist/utils/providerRetry.js

@@ -0,0 +1,113 @@
+/**
+ * Provider-level retry utility for AI SDK calls (NL11)
+ *
+ * The Vercel AI SDK's `generateText()` and `streamText()` have built-in retry
+ * logic (`_retryWithExponentialBackoff()` with default `maxRetries: 2`) that
+ * retries on HTTP 429/500/503. These retries are completely invisible to OTel
+ * because they happen inside the AI SDK.
+ *
+ * This module provides an instrumented retry wrapper that:
+ * 1. Disables the AI SDK's internal retries (via `maxRetries: 0`)
+ * 2. Implements our own retry loop with full OTel span events
+ * 3. Records retry attempts, delays, status codes, and total attempt count
+ *
+ * @module utils/providerRetry
+ */
+import {} from "@opentelemetry/api";
+import { APICallError } from "@ai-sdk/provider";
+import { logger } from "./logger.js";
+/** Maximum number of retry attempts after the initial call (total = 1 + MAX_PROVIDER_RETRIES). */
+export const MAX_PROVIDER_RETRIES = 2;
+/** Base delay in ms for exponential backoff between retries. */
+export const BASE_RETRY_DELAY_MS = 1000;
+/**
+ * Check whether an error thrown by the AI SDK is retryable.
+ *
+ * Uses `APICallError.isInstance()` for proper type-safe detection (the class
+ * uses a branded symbol marker, so `instanceof` doesn't work across package
+ * boundaries). Falls back to duck-typing for non-APICallError cases.
+ */
+export function isRetryableProviderError(error) {
+    // Preferred path: use the AI SDK's own branded type check + isRetryable flag
+    if (APICallError.isInstance(error)) {
+        return error.isRetryable;
+    }
+    // Fallback: duck-type for status codes on errors that aren't APICallError
+    if (error && typeof error === "object" && "statusCode" in error) {
+        const statusCode = error.statusCode;
+        return statusCode === 429 || statusCode >= 500;
+    }
+    return false;
+}
+/**
+ * Extract the HTTP status code from an AI SDK error, if available.
+ */
+export function getErrorStatusCode(error) {
+    if (APICallError.isInstance(error)) {
+        return error.statusCode;
+    }
+    if (error && typeof error === "object" && "statusCode" in error) {
+        return error.statusCode;
+    }
+    return undefined;
+}
+/**
+ * Execute a provider call with instrumented retry logic.
+ *
+ * @param operation  - The async operation to execute (should already use `maxRetries: 0`)
+ * @param span       - The OTel span to annotate with retry events and attributes
+ * @param label      - A human-readable label for log messages (e.g. "generateText", "streamText")
+ * @returns The result of the operation
+ */
+export async function withProviderRetry(operation, span, label) {
+    for (let attempt = 0; attempt <= MAX_PROVIDER_RETRIES; attempt++) {
+        try {
+            const result = await operation();
+            // Record how many attempts it took on the span
+            span.setAttribute("gen_ai.provider.total_attempts", attempt + 1);
+            if (attempt > 0) {
+                logger.info(`[providerRetry] ${label} succeeded after ${attempt + 1} attempts`);
+            }
+            return result;
+        }
+        catch (error) {
+            const retryable = isRetryableProviderError(error);
+            const statusCode = getErrorStatusCode(error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (!retryable || attempt === MAX_PROVIDER_RETRIES) {
+                // Record failure details before re-throwing
+                span.setAttribute("gen_ai.provider.total_attempts", attempt + 1);
+                if (attempt > 0) {
+                    span.setAttribute("gen_ai.provider.retries_exhausted", true);
+                }
+                logger.warn(`[providerRetry] ${label} failed (non-retryable or retries exhausted)`, {
+                    attempt: attempt + 1,
+                    retryable,
+                    statusCode,
+                    error: errorMessage,
+                });
+                throw error;
+            }
+            // Calculate exponential backoff delay
+            const delay = BASE_RETRY_DELAY_MS * Math.pow(2, attempt);
+            // Record retry event on the OTel span
+            span.addEvent("gen_ai.provider.retry", {
+                "retry.attempt": attempt + 1,
+                "retry.delay_ms": delay,
+                ...(statusCode !== undefined && { "retry.status_code": statusCode }),
+                "retry.error": errorMessage.slice(0, 256),
+            });
+            logger.warn(`[providerRetry] ${label} retrying after ${statusCode || "unknown"} error`, {
+                attempt: attempt + 1,
+                maxRetries: MAX_PROVIDER_RETRIES,
+                delayMs: delay,
+                statusCode,
+                error: errorMessage,
+            });
+            await new Promise((r) => setTimeout(r, delay));
+        }
+    }
+    // This should never be reached due to the throw inside the loop,
+    // but TypeScript requires it for exhaustiveness.
+    throw new Error(`[providerRetry] ${label} exhausted all retries`);
+}

package/dist/utils/retryability.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared HTTP retryability constants.
+ *
+ * Centralises the status-code lists that were duplicated across
+ * httpRetryHandler, neurolink.ts, fileDetector.ts, and errorHelpers.
+ */
+/** Server-side and rate-limiting codes worth retrying. */
+export declare const RETRYABLE_HTTP_STATUS_CODES: readonly number[];
+/** Client-error codes where retrying is pointless. */
+export declare const NON_RETRYABLE_HTTP_STATUS_CODES: readonly number[];
+/** Check whether an HTTP status code is retryable. */
+export declare function isRetryableStatusCode(code: number): boolean;
+/** Check whether an HTTP status code is non-retryable. */
+export declare function isNonRetryableStatusCode(code: number): boolean;

package/dist/utils/retryability.js

@@ -0,0 +1,22 @@
+/**
+ * Shared HTTP retryability constants.
+ *
+ * Centralises the status-code lists that were duplicated across
+ * httpRetryHandler, neurolink.ts, fileDetector.ts, and errorHelpers.
+ */
+/** Server-side and rate-limiting codes worth retrying. */
+export const RETRYABLE_HTTP_STATUS_CODES = [
+    408, 429, 500, 502, 503, 504,
+];
+/** Client-error codes where retrying is pointless. */
+export const NON_RETRYABLE_HTTP_STATUS_CODES = [
+    400, 401, 403, 404, 405, 409, 422,
+];
+/** Check whether an HTTP status code is retryable. */
+export function isRetryableStatusCode(code) {
+    return RETRYABLE_HTTP_STATUS_CODES.includes(code);
+}
+/** Check whether an HTTP status code is non-retryable. */
+export function isNonRetryableStatusCode(code) {
+    return NON_RETRYABLE_HTTP_STATUS_CODES.includes(code);
+}

package/dist/utils/sanitizers/svg.js

@@ -339,8 +339,7 @@ function removeDangerousAttributes(content, removedItems) {
         // Parse attributes
         const attrRegex = /([a-zA-Z][a-zA-Z0-9:_-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
         const safeAttrs = [];
-        let attrMatch = attrRegex.exec(attrs);
-        while (attrMatch !== null) {
+        for (let attrMatch = attrRegex.exec(attrs); attrMatch !== null; attrMatch = attrRegex.exec(attrs)) {
             const attrName = attrMatch[1];
             const attrValue = attrMatch[2] ?? attrMatch[3] ?? "";
             const lowerAttrName = attrName.toLowerCase();
@@ -390,13 +389,13 @@ function removeDangerousAttributes(content, removedItems) {
             }
             // Attribute is safe, keep it
             safeAttrs.push(`${attrName}="${escapeAttributeValue(attrValue)}"`);
-            // Get next match
-            attrMatch = attrRegex.exec(attrs);
         }
         // Also keep standalone attributes (like xmlns without value in some cases)
         const standaloneAttrRegex = /\s([a-zA-Z][a-zA-Z0-9:_-]*)(?=\s|>|$|\/)/g;
         let standaloneMatch = standaloneAttrRegex.exec(attrs);
-        while (standaloneMatch !== null) {
+        let iterations = 0;
+        const MAX_ITERATIONS = 1000;
+        while (standaloneMatch !== null && iterations++ < MAX_ITERATIONS) {
             const attrName = standaloneMatch[1];
             // Only keep if it looks like a valid attribute and is safe
             if (SAFE_SVG_ATTRIBUTES.has(attrName) ||

package/dist/utils/tokenEstimation.d.ts

@@ -16,7 +16,17 @@ import type { ChatMessage } from "../types/conversation.js";
 export declare const CHARS_PER_TOKEN = 4;
 /** Characters per token for code */
 export declare const CODE_CHARS_PER_TOKEN = 3;
-/** Safety margin to avoid underestimation */
+/**
+ * Safety margin: additive fraction of baseTokens added to the provider-adjusted estimate.
+ * Using additive margin prevents compounding with provider multipliers.
+ *
+ * Old behavior: baseTokens * providerMultiplier * 1.15  (compounding)
+ *   e.g. Anthropic: baseTokens * 1.23 * 1.15 = baseTokens * 1.4145
+ * New behavior: baseTokens * providerMultiplier + baseTokens * 0.05  (additive)
+ *   e.g. Anthropic: baseTokens * 1.23 + baseTokens * 0.05 = baseTokens * 1.28
+ */
+export declare const TOKEN_SAFETY_MARGIN_ADDITIVE = 0.05;
+/** @deprecated Use TOKEN_SAFETY_MARGIN_ADDITIVE instead. Kept for backward compatibility. */
 export declare const TOKEN_SAFETY_MARGIN = 1.15;
 /** Message framing overhead in tokens (role + delimiters) */
 export declare const TOKENS_PER_MESSAGE = 4;

package/dist/utils/tokenEstimation.js

@@ -15,7 +15,17 @@
 export const CHARS_PER_TOKEN = 4;
 /** Characters per token for code */
 export const CODE_CHARS_PER_TOKEN = 3;
-/** Safety margin to avoid underestimation */
+/**
+ * Safety margin: additive fraction of baseTokens added to the provider-adjusted estimate.
+ * Using additive margin prevents compounding with provider multipliers.
+ *
+ * Old behavior: baseTokens * providerMultiplier * 1.15  (compounding)
+ *   e.g. Anthropic: baseTokens * 1.23 * 1.15 = baseTokens * 1.4145
+ * New behavior: baseTokens * providerMultiplier + baseTokens * 0.05  (additive)
+ *   e.g. Anthropic: baseTokens * 1.23 + baseTokens * 0.05 = baseTokens * 1.28
+ */
+export const TOKEN_SAFETY_MARGIN_ADDITIVE = 0.05;
+/** @deprecated Use TOKEN_SAFETY_MARGIN_ADDITIVE instead. Kept for backward compatibility. */
 export const TOKEN_SAFETY_MARGIN = 1.15;
 /** Message framing overhead in tokens (role + delimiters) */
 export const TOKENS_PER_MESSAGE = 4;
@@ -64,7 +74,11 @@ export function estimateTokens(text, provider, isCode) {
     const charsPerToken = isCode ? CODE_CHARS_PER_TOKEN : CHARS_PER_TOKEN;
     const baseTokens = Math.ceil(text.length / charsPerToken);
     const multiplier = getProviderMultiplier(provider);
-    return Math.ceil(baseTokens * multiplier * TOKEN_SAFETY_MARGIN);
+    // Apply provider multiplier and additive safety margin separately
+    // This prevents compounding (e.g. Anthropic: 1.23 * 1.15 = 1.41x was too aggressive)
+    const providerAdjusted = baseTokens * multiplier;
+    const safetyBuffer = baseTokens * TOKEN_SAFETY_MARGIN_ADDITIVE;
+    return Math.ceil(providerAdjusted + safetyBuffer);
 }
 /**
  * Estimate token count for a single ChatMessage.
@@ -114,8 +128,9 @@ export function truncateToTokenBudget(text, maxTokens, provider) {
         return { text, truncated: false };
     }
     const multiplier = getProviderMultiplier(provider);
-    const safetyFactor = multiplier * TOKEN_SAFETY_MARGIN;
-    const maxChars = Math.floor((maxTokens / safetyFactor) * CHARS_PER_TOKEN);
+    // Use additive safety margin: effective multiplier = multiplier + additive margin
+    const effectiveMultiplier = multiplier + TOKEN_SAFETY_MARGIN_ADDITIVE;
+    const maxChars = Math.floor((maxTokens / effectiveMultiplier) * CHARS_PER_TOKEN);
     if (maxChars <= 0) {
         return { text: "", truncated: true };
     }

package/dist/utils/videoAnalysisProcessor.js

@@ -21,10 +21,14 @@ export function hasVideoFrames(messages) {
             return false;
         }
         if (Array.isArray(msg.content)) {
-            return msg.content.some((part) => typeof part === "object" &&
+            // Count image parts — only route to video analysis pipeline when there are
+            // multiple frames (3+), indicating actual video frame extraction.
+            // Single images or pairs should use the model's native vision capability.
+            const imageCount = msg.content.filter((part) => typeof part === "object" &&
                 part !== null &&
                 "type" in part &&
-                part.type === "image");
+                part.type === "image").length;
+            return imageCount >= 3;
         }
         return false;
     });
@@ -53,7 +57,7 @@ export async function executeVideoAnalysis(messages, options) {
             ? undefined
             : process.env.GOOGLE_VERTEX_PROJECT || process.env.GOOGLE_CLOUD_PROJECT,
         location: options.region || process.env.GOOGLE_VERTEX_LOCATION,
-        model: options.model || "gemini-2.0-flash",
+        model: options.model || "gemini-2.5-flash",
     });
     logger.debug("[VideoAnalysisProcessor] Video analysis completed", {
         hasResult: !!videoAnalysisText,