@juspay/neurolink 10.8.2 → 10.8.4

package/dist/types/config.d.ts

@@ -29,12 +29,15 @@ export type NeuroLinkConfig = {
 /**
  * Curator P2-3: callback signature for centralized fallback policy. When an
  * explicit callback is configured (per-call or instance), it is invoked for
- * ANY error thrown by a generate/stream call except client aborts — network
- * errors, 5xx, timeouts, auth failures included. The callback receives the
- * error unmodified so hosts can classify it themselves (status codes,
- * `isNonRetryableProviderError`, …). Return `{ provider, model }` (either /
- * both optional) to drive a retry; return `null` to bubble the original
- * error untouched.
+ * ANY error thrown by a generate/stream call except genuine caller cancels —
+ * network errors, 5xx, timeouts, auth failures included. A caller cancel is
+ * identified by the caller-supplied `abortSignal` having fired, not by error
+ * shape: abort-shaped errors from NeuroLink's own turn/stall watchdogs and
+ * per-step timeouts DO invoke the callback, so provider hangs can fall back.
+ * The callback receives the error unmodified so hosts can classify it
+ * themselves (status codes, `isNonRetryableProviderError`, …). Return
+ * `{ provider, model }` (either / both optional) to drive a retry; return
+ * `null` to bubble the original error untouched.
  */
 export type ProviderFallbackCallback = (error: unknown) => Promise<{
     provider?: string;
@@ -70,11 +73,13 @@ export type NeurolinkConstructorConfig = {
     credentials?: NeurolinkCredentials;
     /**
      * Curator P2-3: callback invoked when a generate/stream call fails with
-     * any error except a client abort (network errors, 5xx, timeouts, auth
-     * failures, model-access-denied, …). Lets a host (e.g. Curator) centrally
-     * drive fallback policy — "provider A primary, provider B on failure".
-     * The callback receives the original error unmodified and returns the
-     * next `{ provider, model }` to try, or `null` to bubble the error.
+     * any error except a genuine caller cancel — i.e. the caller-supplied
+     * `abortSignal` fired (network errors, 5xx, timeouts, auth failures,
+     * model-access-denied, and internal watchdog aborts all invoke it). Lets
+     * a host (e.g. Curator) centrally drive fallback policy — "provider A
+     * primary, provider B on failure". The callback receives the original
+     * error unmodified and returns the next `{ provider, model }` to try, or
+     * `null` to bubble the error.
      */
     providerFallback?: ProviderFallbackCallback;
     /**

package/dist/types/generate.d.ts

@@ -577,9 +577,11 @@ export type GenerateOptions = {
     /**
      * Curator P2-3: per-call fallback callback. Overrides any
      * instance-level `providerFallback` set on `new NeuroLink({...})`.
-     * Invoked for any error except client aborts (network errors, 5xx,
-     * timeouts, auth failures, model-access-denied, …); receives the error
-     * unmodified. Return `{ provider, model }` to retry, `null` to bubble.
+     * Invoked for any error except a genuine caller cancel — i.e. this
+     * call's `abortSignal` fired (network errors, 5xx, timeouts, auth
+     * failures, model-access-denied, and internal watchdog aborts all invoke
+     * it); receives the error unmodified. Return `{ provider, model }` to
+     * retry, `null` to bubble.
      */
     providerFallback?: (error: unknown) => Promise<{
         provider?: string;

package/dist/types/providers.d.ts

@@ -925,6 +925,8 @@ export type AnthropicVertexSettings = {
     region: string;
     /** SDK request timeout in milliseconds */
     timeout?: number;
+    /** SDK-internal retry budget (transport retries are the orchestrator's job) */
+    maxRetries?: number;
 };
 /**
  * OpenAI-compatible models endpoint response structure

package/dist/types/stream.d.ts

@@ -487,11 +487,12 @@ export type StreamOptions = {
     /**
      * Curator P2-3: per-call fallback callback. Overrides any
      * instance-level `providerFallback` set on `new NeuroLink({...})`.
-     * Invoked for any error thrown while establishing the stream, except
-     * client aborts (network errors, 5xx, timeouts, auth failures,
-     * model-access-denied, …); receives the error unmodified. There is no
-     * mid-stream resume once chunks are flowing. Return `{ provider,
-     * model }` to retry, `null` to bubble.
+     * Invoked for any error thrown while establishing the stream, except a
+     * genuine caller cancel — i.e. this call's `abortSignal` fired (network
+     * errors, 5xx, timeouts, auth failures, model-access-denied, and
+     * internal watchdog aborts all invoke it); receives the error
+     * unmodified. There is no mid-stream resume once chunks are flowing.
+     * Return `{ provider, model }` to retry, `null` to bubble.
      */
     providerFallback?: (error: unknown) => Promise<{
         provider?: string;

package/dist/utils/providerRetry.d.ts

@@ -20,8 +20,16 @@ export declare const MAX_PROVIDER_RETRIES = 2;
 export declare const BASE_RETRY_DELAY_MS = 1000;
 /** Minimum delay in ms when a retryable response provides no retry timing. */
 export declare const NO_HINT_FLOOR_MS = 10000;
-/** Maximum server-requested retry delay honored by provider retries. */
-export declare const MAX_RETRY_AFTER_MS = 120000;
+/**
+ * Maximum server-requested retry delay honored by provider retries.
+ *
+ * A hint above this cap is not clamped-and-slept: the server declared an
+ * unavailability window we are not willing to wait out, so the error is
+ * surfaced immediately instead — fallback orchestration (providerFallback /
+ * modelChain) can route to another provider, and callers without fallback
+ * get a prompt rate-limit error rather than a silent multi-minute stall.
+ */
+export declare const MAX_RETRY_AFTER_MS = 60000;
 /**
  * Check whether an error thrown by the AI SDK is retryable.
  *
@@ -29,6 +37,21 @@ export declare const MAX_RETRY_AFTER_MS = 120000;
  * uses a branded symbol marker, so `instanceof` doesn't work across package
  * boundaries). Falls back to duck-typing for non-APICallError cases.
  */
+/**
+ * Duck-typed HTTP status extraction for errors of unknown provenance.
+ * NeuroLink's hand-rolled clients stamp `.statusCode`; official SDK errors
+ * (e.g. @anthropic-ai/sdk APIError) expose `.status`. Shared with
+ * baseProvider's handleProviderError metadata preservation.
+ */
+export declare function duckTypedStatusCode(error: unknown): number | undefined;
+/**
+ * Duck-typed Retry-After extraction for errors of unknown provenance.
+ * Reads a pre-parsed `.retryAfterMs` (stamped by metadata-preserving
+ * wrappers like handleProviderError), then `.headers` (Headers instance or
+ * record — e.g. @anthropic-ai/sdk APIError), then `.responseHeaders` (the
+ * hand-rolled OpenAI-compatible client's record). Shared with baseProvider.
+ */
+export declare function extractRetryAfterMsFromError(error: unknown): number | undefined;
 export declare function isRetryableProviderError(error: unknown): boolean;
 /**
  * Extract the HTTP status code from an AI SDK error, if available.

package/dist/utils/providerRetry.js

@@ -23,8 +23,16 @@ export const MAX_PROVIDER_RETRIES = 2;
 export const BASE_RETRY_DELAY_MS = 1000;
 /** Minimum delay in ms when a retryable response provides no retry timing. */
 export const NO_HINT_FLOOR_MS = 10_000;
-/** Maximum server-requested retry delay honored by provider retries. */
-export const MAX_RETRY_AFTER_MS = 120_000;
+/**
+ * Maximum server-requested retry delay honored by provider retries.
+ *
+ * A hint above this cap is not clamped-and-slept: the server declared an
+ * unavailability window we are not willing to wait out, so the error is
+ * surfaced immediately instead — fallback orchestration (providerFallback /
+ * modelChain) can route to another provider, and callers without fallback
+ * get a prompt rate-limit error rather than a silent multi-minute stall.
+ */
+export const MAX_RETRY_AFTER_MS = 60_000;
 const sleepWithTimeout = (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs));
 /**
  * Check whether an error thrown by the AI SDK is retryable.
@@ -33,6 +41,54 @@ const sleepWithTimeout = (delayMs) => new Promise((resolve) => setTimeout(resolv
  * uses a branded symbol marker, so `instanceof` doesn't work across package
  * boundaries). Falls back to duck-typing for non-APICallError cases.
  */
+/**
+ * Duck-typed HTTP status extraction for errors of unknown provenance.
+ * NeuroLink's hand-rolled clients stamp `.statusCode`; official SDK errors
+ * (e.g. @anthropic-ai/sdk APIError) expose `.status`. Shared with
+ * baseProvider's handleProviderError metadata preservation.
+ */
+export function duckTypedStatusCode(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const err = error;
+    if (typeof err.statusCode === "number") {
+        return err.statusCode;
+    }
+    if (typeof err.status === "number") {
+        return err.status;
+    }
+    return undefined;
+}
+/**
+ * Duck-typed Retry-After extraction for errors of unknown provenance.
+ * Reads a pre-parsed `.retryAfterMs` (stamped by metadata-preserving
+ * wrappers like handleProviderError), then `.headers` (Headers instance or
+ * record — e.g. @anthropic-ai/sdk APIError), then `.responseHeaders` (the
+ * hand-rolled OpenAI-compatible client's record). Shared with baseProvider.
+ */
+export function extractRetryAfterMsFromError(error) {
+    if (!error || typeof error !== "object") {
+        return undefined;
+    }
+    const err = error;
+    // Number.isFinite rejects NaN/Infinity: typeof NaN === "number", and a NaN
+    // hint would survive Math.max() into sleep(NaN) — an immediate retry
+    // instead of the no-hint floor.
+    if (typeof err.retryAfterMs === "number" &&
+        Number.isFinite(err.retryAfterMs)) {
+        return err.retryAfterMs;
+    }
+    for (const candidate of [err.headers, err.responseHeaders]) {
+        if (candidate && typeof candidate === "object") {
+            const parsed = parseRetryAfterMs(candidate);
+            if (parsed !== undefined) {
+                return parsed;
+            }
+        }
+    }
+    return undefined;
+}
 export function isRetryableProviderError(error) {
     // Preferred path: use the AI SDK's own branded type check + isRetryable flag
     if (APICallError.isInstance(error)) {
@@ -42,8 +98,8 @@ export function isRetryableProviderError(error) {
         return error.retriable;
     }
     // Fallback: duck-type for status codes on errors that aren't APICallError
-    if (error && typeof error === "object" && "statusCode" in error) {
-        const statusCode = error.statusCode;
+    const statusCode = duckTypedStatusCode(error);
+    if (statusCode !== undefined) {
         return statusCode === 429 || statusCode >= 500;
     }
     return false;
@@ -55,10 +111,7 @@ export function getErrorStatusCode(error) {
     if (APICallError.isInstance(error)) {
         return error.statusCode;
     }
-    if (error && typeof error === "object" && "statusCode" in error) {
-        return error.statusCode;
-    }
-    return undefined;
+    return duckTypedStatusCode(error);
 }
 function getRetryAfterMs(error) {
     if (APICallError.isInstance(error) && error.responseHeaders) {
@@ -67,10 +120,12 @@ function getRetryAfterMs(error) {
             return parsedDelay;
         }
     }
-    if (error instanceof NeuroLinkError && error.retryAfterMs !== undefined) {
+    if (error instanceof NeuroLinkError &&
+        error.retryAfterMs !== undefined &&
+        Number.isFinite(error.retryAfterMs)) {
         return error.retryAfterMs;
     }
-    return undefined;
+    return extractRetryAfterMsFromError(error);
 }
 /**
  * Execute a provider call with instrumented retry logic.
@@ -110,10 +165,29 @@ export async function withProviderRetry(operation, span, label, sleep = sleepWit
                 throw error;
             }
             const retryAfterMs = getRetryAfterMs(error);
-            const boundedRetryAfterMs = retryAfterMs === undefined
-                ? undefined
-                : Math.min(MAX_RETRY_AFTER_MS, Math.max(0, retryAfterMs));
-            const delay = boundedRetryAfterMs ??
+            if (retryAfterMs !== undefined && retryAfterMs > MAX_RETRY_AFTER_MS) {
+                span?.setAttribute("gen_ai.provider.total_attempts", attempt + 1);
+                span?.addEvent("gen_ai.provider.retry_suppressed", {
+                    "retry.after_ms": retryAfterMs,
+                    ...(statusCode !== undefined && { "retry.status_code": statusCode }),
+                });
+                // Best-effort stamp so upper retry layers (the MCP generation loop's
+                // isRetryable check) also surface instead of re-running a
+                // rate-limited provider.
+                try {
+                    Object.assign(error, {
+                        isRetryable: false,
+                        retryAfterMs,
+                    });
+                }
+                catch {
+                    /* frozen error — the throw below still surfaces it */
+                }
+                logger.warn(`[providerRetry] ${label} not retrying — server requested a ` +
+                    `${Math.round(retryAfterMs / 1000)}s wait (cap ${MAX_RETRY_AFTER_MS / 1000}s); surfacing for fallback`, { attempt: attempt + 1, retryAfterMs, statusCode });
+                throw error;
+            }
+            const delay = (retryAfterMs === undefined ? undefined : Math.max(0, retryAfterMs)) ??
                 Math.max(BASE_RETRY_DELAY_MS * Math.pow(2, attempt), NO_HINT_FLOOR_MS);
             // Record retry event on the OTel span
             span?.addEvent("gen_ai.provider.retry", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "10.8.2",
+  "version": "10.8.4",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -95,6 +95,7 @@
     "test:mcp:infra": "npx tsx test/continuous-test-suite-mcp-infra.ts",
     "test:providers-mocked": "npx tsx test/continuous-test-suite-providers-mocked.ts",
     "test:provider-fallback": "npx tsx test/continuous-test-suite-provider-fallback.ts",
+    "test:provider-fallback-latency": "npx tsx test/continuous-test-suite-provider-fallback-latency.ts",
     "test:rag": "npx tsx test/continuous-test-suite-rag.ts",
     "test:vector-pinecone": "npx tsx test/continuous-test-suite-vector-pinecone.ts",
     "test:vector-pgvector": "npx tsx test/continuous-test-suite-vector-pgvector.ts",