@juspay/neurolink 9.14.0 → 9.16.0

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,

package/dist/workflow/config.d.ts

@@ -256,9 +256,9 @@ export declare const ModelGroupSchema: z.ZodObject<{
     continueOnFailure: boolean;
     minSuccessful: number;
     timeout?: number | undefined;
-    metadata?: Record<string, JsonValue> | undefined;
-    name?: string | undefined;
     description?: string | undefined;
+    name?: string | undefined;
+    metadata?: Record<string, JsonValue> | undefined;
     parallelism?: number | undefined;
 }, {
     id: string;
@@ -279,9 +279,9 @@ export declare const ModelGroupSchema: z.ZodObject<{
     }[];
     executionStrategy: "parallel" | "sequential";
     timeout?: number | undefined;
-    metadata?: Record<string, JsonValue> | undefined;
-    name?: string | undefined;
     description?: string | undefined;
+    name?: string | undefined;
+    metadata?: Record<string, JsonValue> | undefined;
     continueOnFailure?: boolean | undefined;
     minSuccessful?: number | undefined;
     parallelism?: number | undefined;
@@ -458,9 +458,9 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         continueOnFailure: boolean;
         minSuccessful: number;
         timeout?: number | undefined;
-        metadata?: Record<string, JsonValue> | undefined;
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
+        metadata?: Record<string, JsonValue> | undefined;
         parallelism?: number | undefined;
     }, {
         id: string;
@@ -481,9 +481,9 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         }[];
         executionStrategy: "parallel" | "sequential";
         timeout?: number | undefined;
-        metadata?: Record<string, JsonValue> | undefined;
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
+        metadata?: Record<string, JsonValue> | undefined;
         continueOnFailure?: boolean | undefined;
         minSuccessful?: number | undefined;
         parallelism?: number | undefined;
@@ -749,6 +749,7 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         enableTracing?: boolean | undefined;
     } | undefined;
     version?: string | undefined;
+    description?: string | undefined;
     metadata?: Record<string, JsonValue> | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
@@ -787,7 +788,6 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         addModelAttribution?: boolean | undefined;
         addExecutionTime?: boolean | undefined;
     } | undefined;
-    description?: string | undefined;
     modelGroups?: {
         id: string;
         models: {
@@ -809,9 +809,9 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         continueOnFailure: boolean;
         minSuccessful: number;
         timeout?: number | undefined;
-        metadata?: Record<string, JsonValue> | undefined;
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
+        metadata?: Record<string, JsonValue> | undefined;
         parallelism?: number | undefined;
     }[] | undefined;
     defaultSystemPrompt?: string | undefined;
@@ -871,6 +871,7 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         enableTracing?: boolean | undefined;
     } | undefined;
     version?: string | undefined;
+    description?: string | undefined;
     metadata?: Record<string, JsonValue> | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
@@ -909,7 +910,6 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         addModelAttribution?: boolean | undefined;
         addExecutionTime?: boolean | undefined;
     } | undefined;
-    description?: string | undefined;
     modelGroups?: {
         id: string;
         models: {
@@ -929,9 +929,9 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         }[];
         executionStrategy: "parallel" | "sequential";
         timeout?: number | undefined;
-        metadata?: Record<string, JsonValue> | undefined;
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
+        metadata?: Record<string, JsonValue> | undefined;
         continueOnFailure?: boolean | undefined;
         minSuccessful?: number | undefined;
         parallelism?: number | undefined;
@@ -993,6 +993,7 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         enableTracing?: boolean | undefined;
     } | undefined;
     version?: string | undefined;
+    description?: string | undefined;
     metadata?: Record<string, JsonValue> | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
@@ -1031,7 +1032,6 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         addModelAttribution?: boolean | undefined;
         addExecutionTime?: boolean | undefined;
     } | undefined;
-    description?: string | undefined;
     modelGroups?: {
         id: string;
         models: {
@@ -1053,9 +1053,9 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         continueOnFailure: boolean;
         minSuccessful: number;
         timeout?: number | undefined;
-        metadata?: Record<string, JsonValue> | undefined;
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
+        metadata?: Record<string, JsonValue> | undefined;
         parallelism?: number | undefined;
     }[] | undefined;
     defaultSystemPrompt?: string | undefined;
@@ -1115,6 +1115,7 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         enableTracing?: boolean | undefined;
     } | undefined;
     version?: string | undefined;
+    description?: string | undefined;
     metadata?: Record<string, JsonValue> | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
@@ -1153,7 +1154,6 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         addModelAttribution?: boolean | undefined;
         addExecutionTime?: boolean | undefined;
     } | undefined;
-    description?: string | undefined;
     modelGroups?: {
         id: string;
         models: {
@@ -1173,9 +1173,9 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         }[];
         executionStrategy: "parallel" | "sequential";
         timeout?: number | undefined;
-        metadata?: Record<string, JsonValue> | undefined;
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
+        metadata?: Record<string, JsonValue> | undefined;
         continueOnFailure?: boolean | undefined;
         minSuccessful?: number | undefined;
         parallelism?: number | undefined;
@@ -1237,6 +1237,7 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         enableTracing?: boolean | undefined;
     } | undefined;
     version?: string | undefined;
+    description?: string | undefined;
     metadata?: Record<string, JsonValue> | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
@@ -1275,7 +1276,6 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         addModelAttribution?: boolean | undefined;
         addExecutionTime?: boolean | undefined;
     } | undefined;
-    description?: string | undefined;
     modelGroups?: {
         id: string;
         models: {
@@ -1297,9 +1297,9 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         continueOnFailure: boolean;
         minSuccessful: number;
         timeout?: number | undefined;
-        metadata?: Record<string, JsonValue> | undefined;
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
+        metadata?: Record<string, JsonValue> | undefined;
         parallelism?: number | undefined;
     }[] | undefined;
     defaultSystemPrompt?: string | undefined;
@@ -1359,6 +1359,7 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         enableTracing?: boolean | undefined;
     } | undefined;
     version?: string | undefined;
+    description?: string | undefined;
     metadata?: Record<string, JsonValue> | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
@@ -1397,7 +1398,6 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         addModelAttribution?: boolean | undefined;
         addExecutionTime?: boolean | undefined;
     } | undefined;
-    description?: string | undefined;
     modelGroups?: {
         id: string;
         models: {
@@ -1417,9 +1417,9 @@ export declare const WorkflowConfigSchema: z.ZodEffects<z.ZodEffects<z.ZodObject
         }[];
         executionStrategy: "parallel" | "sequential";
         timeout?: number | undefined;
-        metadata?: Record<string, JsonValue> | undefined;
-        name?: string | undefined;
         description?: string | undefined;
+        name?: string | undefined;
+        metadata?: Record<string, JsonValue> | undefined;
         continueOnFailure?: boolean | undefined;
         minSuccessful?: number | undefined;
         parallelism?: number | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.14.0",
+  "version": "9.16.0",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
     "name": "Juspay Technologies",
@@ -214,6 +214,7 @@
     "music-metadata": "^11.11.2",
     "nanoid": "^5.1.5",
     "ollama-ai-provider": "^1.2.0",
+    "open": "^11.0.0",
     "ora": "^7.0.1",
     "p-limit": "^6.2.0",
     "pdf-parse": "^2.4.5",