@juspay/neurolink 10.8.1 → 10.8.2

package/dist/lib/neurolink.d.ts

@@ -718,7 +718,7 @@ export declare class NeuroLink {
      * Curator P2-3: wraps a generate/stream call with the fallback
      * orchestration (`providerFallback` callback + `modelChain` walker).
      *
-     * On a model-access-denied error from the inner call:
+     * On a qualifying error from the inner call:
      *  1. Resolve the effective callback (per-call > instance > synthesised
      *     from modelChain) and the effective chain (per-call > instance).
      *  2. Walk attempts: invoke callback (or pop next chain entry) → emit
@@ -726,6 +726,12 @@ export declare class NeuroLink {
      *     model}.
      *  3. Stop on first success, on a callback returning null, or after
      *     exhausting the chain (throw the most recent error).
+     *
+     * What qualifies depends on how fallback was configured: an EXPLICIT
+     * `providerFallback` callback is consulted for any error except client
+     * aborts (the callback owns the decision — it receives the error
+     * unmodified and can return null to bubble), while modelChain-only
+     * configs keep the narrow model-access-denied gate.
      */
     private runWithFallbackOrchestration;
     private attemptInner;

package/dist/lib/neurolink.js

@@ -3261,7 +3261,7 @@ Current user's request: ${currentInput}`;
      * Curator P2-3: wraps a generate/stream call with the fallback
      * orchestration (`providerFallback` callback + `modelChain` walker).
      *
-     * On a model-access-denied error from the inner call:
+     * On a qualifying error from the inner call:
      *  1. Resolve the effective callback (per-call > instance > synthesised
      *     from modelChain) and the effective chain (per-call > instance).
      *  2. Walk attempts: invoke callback (or pop next chain entry) → emit
@@ -3269,6 +3269,12 @@ Current user's request: ${currentInput}`;
      *     model}.
      *  3. Stop on first success, on a callback returning null, or after
      *     exhausting the chain (throw the most recent error).
+     *
+     * What qualifies depends on how fallback was configured: an EXPLICIT
+     * `providerFallback` callback is consulted for any error except client
+     * aborts (the callback owns the decision — it receives the error
+     * unmodified and can return null to bubble), while modelChain-only
+     * configs keep the narrow model-access-denied gate.
      */
     async runWithFallbackOrchestration(optionsOrPrompt, kind, inner) {
         const initialAttempt = await this.attemptInner(inner, optionsOrPrompt);
@@ -3276,10 +3282,8 @@ Current user's request: ${currentInput}`;
             return initialAttempt.ok;
         }
         let lastError = initialAttempt.error;
-        if (!looksLikeModelAccessDenied(lastError)) {
-            throw lastError;
-        }
-        // Build the chain orchestration.
+        // Resolve the fallback configuration BEFORE gating so the gate can
+        // distinguish an explicit callback from a modelChain-only setup.
         const requestedProvider = (typeof optionsOrPrompt === "object"
             ? optionsOrPrompt.provider
             : undefined);
@@ -3293,6 +3297,14 @@ Current user's request: ${currentInput}`;
         const perCallChain = callOpts.modelChain;
         const effectiveCallback = perCallCallback ?? this.fallbackConfig.providerFallback;
         const effectiveChain = perCallChain ?? this.fallbackConfig.modelChain;
+        // Explicit callback (per-call or instance providerFallback): the callback
+        // owns the decision for any error except client aborts — it can return
+        // null to bubble. modelChain-only keeps the narrow model-access-denied
+        // gate so chain walkers don't retry errors the chain can't fix.
+        const shouldOrchestrateFallback = (err) => effectiveCallback ? !isAbortError(err) : looksLikeModelAccessDenied(err);
+        if (!shouldOrchestrateFallback(lastError)) {
+            throw lastError;
+        }
         if (!effectiveCallback && !effectiveChain) {
             throw lastError;
         }
@@ -3364,7 +3376,7 @@ Current user's request: ${currentInput}`;
             }
             lastError = retryAttempt.error;
             attemptedRequestedModel = next.model ?? attemptedRequestedModel;
-            if (!looksLikeModelAccessDenied(lastError)) {
+            if (!shouldOrchestrateFallback(lastError)) {
                 throw lastError;
             }
         }

package/dist/lib/providers/anthropic.js

@@ -724,6 +724,12 @@ export class AnthropicProvider extends BaseProvider {
                 headers["anthropic-beta"] = ANTHROPIC_BETA_HEADERS["anthropic-beta"];
             }
         }
+        if (usingProxy) {
+            // WAFs in front of ANTHROPIC_BASE_URL proxies commonly block the bare
+            // SDK UA ("Anthropic/JS x.y.z"); send the claude-cli UA the OAuth path
+            // already uses. Direct-to-Anthropic traffic keeps the honest SDK UA.
+            headers["User-Agent"] = CLAUDE_CLI_USER_AGENT;
+        }
         // Add subscription-specific headers if applicable
         if (this.subscriptionTier !== "api") {
             headers["x-subscription-tier"] = this.subscriptionTier;

package/dist/lib/types/config.d.ts

@@ -27,10 +27,14 @@ export type NeuroLinkConfig = {
     [key: string]: unknown;
 };
 /**
- * Curator P2-3: callback signature for centralized fallback policy. Invoked
- * when a generate/stream call fails with what looks like a model-access-denied
- * error. Return `{ provider, model }` (either / both optional) to drive a
- * retry; return `null` to bubble the original error untouched.
+ * 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.
  */
 export type ProviderFallbackCallback = (error: unknown) => Promise<{
     provider?: string;
@@ -65,16 +69,21 @@ export type NeurolinkConstructorConfig = {
      */
     credentials?: NeurolinkCredentials;
     /**
-     * Curator P2-3: callback invoked on model-access-denied. Lets a host (e.g.
-     * Curator) centrally drive fallback policy. The callback receives the
-     * original error and returns the next `{ provider, model }` to try, or
-     * `null` to bubble the error.
+     * 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.
      */
     providerFallback?: ProviderFallbackCallback;
     /**
-     * Curator P2-3: ordered list of model names to try in sequence on
-     * model-access-denied. Sugar over `providerFallback`. The current
-     * provider is preserved across the chain; only the model name changes.
+     * Curator P2-3: ordered list of model names to try in sequence. Sugar
+     * over `providerFallback`, but with a narrower trigger: without an
+     * explicit callback the chain only advances on model-access-denied
+     * errors — other failures (network, 5xx, timeouts) bubble immediately.
+     * The current provider is preserved across the chain; only the model
+     * name changes.
      */
     modelChain?: string[];
     /**

package/dist/lib/types/generate.d.ts

@@ -577,6 +577,9 @@ 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.
      */
     providerFallback?: (error: unknown) => Promise<{
         provider?: string;
@@ -584,7 +587,9 @@ export type GenerateOptions = {
     } | null>;
     /**
      * Curator P2-3: per-call ordered model chain. Overrides any
-     * instance-level `modelChain`. Tried in order on model-access-denied.
+     * instance-level `modelChain`. Without an explicit `providerFallback`
+     * callback the chain only advances on model-access-denied errors —
+     * other failures (network, 5xx, timeouts) bubble immediately.
      */
     modelChain?: string[];
     /**

package/dist/lib/types/stream.d.ts

@@ -487,6 +487,11 @@ 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.
      */
     providerFallback?: (error: unknown) => Promise<{
         provider?: string;
@@ -494,7 +499,9 @@ export type StreamOptions = {
     } | null>;
     /**
      * Curator P2-3: per-call ordered model chain. Overrides any
-     * instance-level `modelChain`. Tried in order on model-access-denied.
+     * instance-level `modelChain`. Without an explicit `providerFallback`
+     * callback the chain only advances on model-access-denied errors —
+     * other failures (network, 5xx, timeouts) bubble immediately.
      */
     modelChain?: string[];
     /**

package/dist/neurolink.d.ts

@@ -718,7 +718,7 @@ export declare class NeuroLink {
      * Curator P2-3: wraps a generate/stream call with the fallback
      * orchestration (`providerFallback` callback + `modelChain` walker).
      *
-     * On a model-access-denied error from the inner call:
+     * On a qualifying error from the inner call:
      *  1. Resolve the effective callback (per-call > instance > synthesised
      *     from modelChain) and the effective chain (per-call > instance).
      *  2. Walk attempts: invoke callback (or pop next chain entry) → emit
@@ -726,6 +726,12 @@ export declare class NeuroLink {
      *     model}.
      *  3. Stop on first success, on a callback returning null, or after
      *     exhausting the chain (throw the most recent error).
+     *
+     * What qualifies depends on how fallback was configured: an EXPLICIT
+     * `providerFallback` callback is consulted for any error except client
+     * aborts (the callback owns the decision — it receives the error
+     * unmodified and can return null to bubble), while modelChain-only
+     * configs keep the narrow model-access-denied gate.
      */
     private runWithFallbackOrchestration;
     private attemptInner;

package/dist/neurolink.js

@@ -3261,7 +3261,7 @@ Current user's request: ${currentInput}`;
      * Curator P2-3: wraps a generate/stream call with the fallback
      * orchestration (`providerFallback` callback + `modelChain` walker).
      *
-     * On a model-access-denied error from the inner call:
+     * On a qualifying error from the inner call:
      *  1. Resolve the effective callback (per-call > instance > synthesised
      *     from modelChain) and the effective chain (per-call > instance).
      *  2. Walk attempts: invoke callback (or pop next chain entry) → emit
@@ -3269,6 +3269,12 @@ Current user's request: ${currentInput}`;
      *     model}.
      *  3. Stop on first success, on a callback returning null, or after
      *     exhausting the chain (throw the most recent error).
+     *
+     * What qualifies depends on how fallback was configured: an EXPLICIT
+     * `providerFallback` callback is consulted for any error except client
+     * aborts (the callback owns the decision — it receives the error
+     * unmodified and can return null to bubble), while modelChain-only
+     * configs keep the narrow model-access-denied gate.
      */
     async runWithFallbackOrchestration(optionsOrPrompt, kind, inner) {
         const initialAttempt = await this.attemptInner(inner, optionsOrPrompt);
@@ -3276,10 +3282,8 @@ Current user's request: ${currentInput}`;
             return initialAttempt.ok;
         }
         let lastError = initialAttempt.error;
-        if (!looksLikeModelAccessDenied(lastError)) {
-            throw lastError;
-        }
-        // Build the chain orchestration.
+        // Resolve the fallback configuration BEFORE gating so the gate can
+        // distinguish an explicit callback from a modelChain-only setup.
         const requestedProvider = (typeof optionsOrPrompt === "object"
             ? optionsOrPrompt.provider
             : undefined);
@@ -3293,6 +3297,14 @@ Current user's request: ${currentInput}`;
         const perCallChain = callOpts.modelChain;
         const effectiveCallback = perCallCallback ?? this.fallbackConfig.providerFallback;
         const effectiveChain = perCallChain ?? this.fallbackConfig.modelChain;
+        // Explicit callback (per-call or instance providerFallback): the callback
+        // owns the decision for any error except client aborts — it can return
+        // null to bubble. modelChain-only keeps the narrow model-access-denied
+        // gate so chain walkers don't retry errors the chain can't fix.
+        const shouldOrchestrateFallback = (err) => effectiveCallback ? !isAbortError(err) : looksLikeModelAccessDenied(err);
+        if (!shouldOrchestrateFallback(lastError)) {
+            throw lastError;
+        }
         if (!effectiveCallback && !effectiveChain) {
             throw lastError;
         }
@@ -3364,7 +3376,7 @@ Current user's request: ${currentInput}`;
             }
             lastError = retryAttempt.error;
             attemptedRequestedModel = next.model ?? attemptedRequestedModel;
-            if (!looksLikeModelAccessDenied(lastError)) {
+            if (!shouldOrchestrateFallback(lastError)) {
                 throw lastError;
             }
         }

package/dist/providers/anthropic.js

@@ -724,6 +724,12 @@ export class AnthropicProvider extends BaseProvider {
                 headers["anthropic-beta"] = ANTHROPIC_BETA_HEADERS["anthropic-beta"];
             }
         }
+        if (usingProxy) {
+            // WAFs in front of ANTHROPIC_BASE_URL proxies commonly block the bare
+            // SDK UA ("Anthropic/JS x.y.z"); send the claude-cli UA the OAuth path
+            // already uses. Direct-to-Anthropic traffic keeps the honest SDK UA.
+            headers["User-Agent"] = CLAUDE_CLI_USER_AGENT;
+        }
         // Add subscription-specific headers if applicable
         if (this.subscriptionTier !== "api") {
             headers["x-subscription-tier"] = this.subscriptionTier;

package/dist/types/config.d.ts

@@ -27,10 +27,14 @@ export type NeuroLinkConfig = {
     [key: string]: unknown;
 };
 /**
- * Curator P2-3: callback signature for centralized fallback policy. Invoked
- * when a generate/stream call fails with what looks like a model-access-denied
- * error. Return `{ provider, model }` (either / both optional) to drive a
- * retry; return `null` to bubble the original error untouched.
+ * 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.
  */
 export type ProviderFallbackCallback = (error: unknown) => Promise<{
     provider?: string;
@@ -65,16 +69,21 @@ export type NeurolinkConstructorConfig = {
      */
     credentials?: NeurolinkCredentials;
     /**
-     * Curator P2-3: callback invoked on model-access-denied. Lets a host (e.g.
-     * Curator) centrally drive fallback policy. The callback receives the
-     * original error and returns the next `{ provider, model }` to try, or
-     * `null` to bubble the error.
+     * 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.
      */
     providerFallback?: ProviderFallbackCallback;
     /**
-     * Curator P2-3: ordered list of model names to try in sequence on
-     * model-access-denied. Sugar over `providerFallback`. The current
-     * provider is preserved across the chain; only the model name changes.
+     * Curator P2-3: ordered list of model names to try in sequence. Sugar
+     * over `providerFallback`, but with a narrower trigger: without an
+     * explicit callback the chain only advances on model-access-denied
+     * errors — other failures (network, 5xx, timeouts) bubble immediately.
+     * The current provider is preserved across the chain; only the model
+     * name changes.
      */
     modelChain?: string[];
     /**

package/dist/types/generate.d.ts

@@ -577,6 +577,9 @@ 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.
      */
     providerFallback?: (error: unknown) => Promise<{
         provider?: string;
@@ -584,7 +587,9 @@ export type GenerateOptions = {
     } | null>;
     /**
      * Curator P2-3: per-call ordered model chain. Overrides any
-     * instance-level `modelChain`. Tried in order on model-access-denied.
+     * instance-level `modelChain`. Without an explicit `providerFallback`
+     * callback the chain only advances on model-access-denied errors —
+     * other failures (network, 5xx, timeouts) bubble immediately.
      */
     modelChain?: string[];
     /**

package/dist/types/stream.d.ts

@@ -487,6 +487,11 @@ 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.
      */
     providerFallback?: (error: unknown) => Promise<{
         provider?: string;
@@ -494,7 +499,9 @@ export type StreamOptions = {
     } | null>;
     /**
      * Curator P2-3: per-call ordered model chain. Overrides any
-     * instance-level `modelChain`. Tried in order on model-access-denied.
+     * instance-level `modelChain`. Without an explicit `providerFallback`
+     * callback the chain only advances on model-access-denied errors —
+     * other failures (network, 5xx, timeouts) bubble immediately.
      */
     modelChain?: string[];
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "10.8.1",
+  "version": "10.8.2",
   "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": {
@@ -94,6 +94,7 @@
     "test:mcp:limits": "npx tsx test/continuous-test-suite-mcp-output-limits.ts",
     "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: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",