@juspay/neurolink 10.8.1 → 10.8.3

package/dist/core/baseProvider.js

@@ -5,6 +5,7 @@ import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
 import { ATTR, tracers } from "../telemetry/index.js";
 import { isAbortError, NeuroLinkError } from "../utils/errorHandling.js";
+import { duckTypedStatusCode, extractRetryAfterMsFromError, } from "../utils/providerRetry.js";
 import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifecycleCallbacks.js";
 import { resolveLifecycleTimeoutMs } from "../utils/lifecycleTimeout.js";
 import { logger } from "../utils/logger.js";
@@ -1488,6 +1489,30 @@ export class BaseProvider {
                 : new DOMException("The operation was aborted", "AbortError");
         }
         const formatted = this.formatProviderError(error);
+        // Preserve transport retry metadata across formatting. Provider
+        // formatters return fresh Error instances (RateLimitError, NetworkError,
+        // …) that would otherwise destroy the classification upper layers need:
+        // performMCPGenerationRetries' isRetryable/status checks and
+        // providerRetry's Retry-After extraction. Copied generically so every
+        // provider's 429/5xx keeps its status and server-requested delay.
+        if (error && typeof error === "object" && formatted !== error) {
+            const src = error;
+            const dst = formatted;
+            const statusCode = duckTypedStatusCode(error);
+            if (statusCode !== undefined && dst.statusCode === undefined) {
+                dst.statusCode = statusCode;
+            }
+            if (typeof src.isRetryable === "boolean" &&
+                dst.isRetryable === undefined) {
+                dst.isRetryable = src.isRetryable;
+            }
+            if (dst.retryAfterMs === undefined) {
+                const retryAfterMs = extractRetryAfterMsFromError(error);
+                if (retryAfterMs !== undefined) {
+                    dst.retryAfterMs = retryAfterMs;
+                }
+            }
+        }
         // Preserve the lifecycle-fired mark across formatting:
         // fireLifecycleErrorCallback() marks the ORIGINAL error in the shared
         // WeakSet, but formatProviderError() typically returns a new Error

package/dist/lib/adapters/providerImageAdapter.js

@@ -45,6 +45,30 @@ const IMAGE_LIMITS = {
  * through and let the underlying provider surface errors if needed.
  */
 const PROXY_PROVIDERS = new Set(["litellm", "openrouter"]);
+/**
+ * Family-level vision rules, checked ONLY after a model id misses the exact
+ * VISION_CAPABILITIES allowlist for its provider. Kept as patterns (mirroring
+ * SAMPLING_PARAM_REJECTING_FAMILIES in modelRegistry.ts) because gateway ids
+ * carry arbitrary prefixes/suffixes (`vertex_ai/claude-sonnet-5@20260203`,
+ * `claude-opus-4-7-20260115`) that exact entries can't cover.
+ *
+ * Matches name-first Claude ids (claude-{opus,sonnet,haiku}-N…) with major
+ * version ≥ 4 — e.g. `claude-sonnet-5`, `claude-opus-5`, `claude-opus-4-7`,
+ * `claude-haiku-4-5` — all of which are vision-capable, plus the
+ * Fable/Mythos-class models (`claude-fable-5`, `claude-mythos-5`).
+ *
+ * Legacy number-first 3.x ids (`claude-3-5-haiku`, `claude-3-haiku`, …)
+ * deliberately do NOT match: the family word follows the version there, and
+ * claude-3-5-haiku — the last non-vision Claude — must stay rejected.
+ */
+const CLAUDE_MODERN_VISION_FAMILIES = [
+    /claude-(?:opus|sonnet|haiku)-(?:[4-9]|\d{2,})/i,
+    /claude-(?:fable|mythos)-\d/i,
+];
+const VISION_FAMILY_RULES = {
+    anthropic: CLAUDE_MODERN_VISION_FAMILIES,
+    vertex: CLAUDE_MODERN_VISION_FAMILIES,
+};
 /**
  * Normalize provider name/alias to its canonical form for vision checks.
  */
@@ -597,6 +621,13 @@ export class ProviderImageAdapter {
     static supportsVision(provider, model) {
         try {
             const normalizedProvider = normalizeVisionProvider(provider);
+            // Anthropic behind a proxy (ANTHROPIC_BASE_URL set) routes to whatever
+            // the proxy exposes — capability gating is the upstream's job. Mirrors
+            // the validateModelAccess tier-check bypass in providers/anthropic.ts.
+            if (normalizedProvider === "anthropic" &&
+                process.env.ANTHROPIC_BASE_URL) {
+                return true;
+            }
             const supportedModels = VISION_CAPABILITIES[normalizedProvider];
             if (!supportedModels) {
                 return false;
@@ -612,6 +643,10 @@ export class ProviderImageAdapter {
                 return true; // Provider supports vision, but need to check specific model
             }
             const modelMatched = supportedModels.some((supportedModel) => model.toLowerCase().includes(supportedModel.toLowerCase()));
+            if (!modelMatched &&
+                VISION_FAMILY_RULES[normalizedProvider]?.some((rule) => rule.test(model))) {
+                return true;
+            }
             // Proxy providers route to arbitrary underlying models — pass through if
             // the model isn't in the known allowlist.
             if (!modelMatched && PROXY_PROVIDERS.has(normalizedProvider)) {

package/dist/lib/core/baseProvider.js

@@ -5,6 +5,7 @@ import { MiddlewareFactory } from "../middleware/factory.js";
 import { modelSupports } from "../models/modelRegistry.js";
 import { ATTR, tracers } from "../telemetry/index.js";
 import { isAbortError, NeuroLinkError } from "../utils/errorHandling.js";
+import { duckTypedStatusCode, extractRetryAfterMsFromError, } from "../utils/providerRetry.js";
 import { hasLifecycleErrorFired, markLifecycleErrorFired, } from "../utils/lifecycleCallbacks.js";
 import { resolveLifecycleTimeoutMs } from "../utils/lifecycleTimeout.js";
 import { logger } from "../utils/logger.js";
@@ -1488,6 +1489,30 @@ export class BaseProvider {
                 : new DOMException("The operation was aborted", "AbortError");
         }
         const formatted = this.formatProviderError(error);
+        // Preserve transport retry metadata across formatting. Provider
+        // formatters return fresh Error instances (RateLimitError, NetworkError,
+        // …) that would otherwise destroy the classification upper layers need:
+        // performMCPGenerationRetries' isRetryable/status checks and
+        // providerRetry's Retry-After extraction. Copied generically so every
+        // provider's 429/5xx keeps its status and server-requested delay.
+        if (error && typeof error === "object" && formatted !== error) {
+            const src = error;
+            const dst = formatted;
+            const statusCode = duckTypedStatusCode(error);
+            if (statusCode !== undefined && dst.statusCode === undefined) {
+                dst.statusCode = statusCode;
+            }
+            if (typeof src.isRetryable === "boolean" &&
+                dst.isRetryable === undefined) {
+                dst.isRetryable = src.isRetryable;
+            }
+            if (dst.retryAfterMs === undefined) {
+                const retryAfterMs = extractRetryAfterMsFromError(error);
+                if (retryAfterMs !== undefined) {
+                    dst.retryAfterMs = retryAfterMs;
+                }
+            }
+        }
         // Preserve the lifecycle-fired mark across formatting:
         // fireLifecycleErrorCallback() marks the ORIGINAL error in the shared
         // WeakSet, but formatProviderError() typically returns a new Error

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

@@ -100,6 +100,7 @@ import { runWorkflow } from "./workflow/core/workflowRunner.js";
 import { ModelPool, classifyProviderError } from "./routing/index.js";
 import { ClassifierRouter } from "./routing/classifierRouter.js";
 import { looksLikeModelAccessDenied as sharedLooksLikeModelAccessDenied, isNonRetryableProviderError as sharedIsNonRetryableProviderError, } from "./utils/providerErrorClassification.js";
+import { getErrorStatusCode } from "./utils/providerRetry.js";
 import { detectAndRedactPII } from "./utils/piiDetector.js";
 import { validateResponse } from "./utils/responseValidator.js";
 /**
@@ -3261,7 +3262,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 +3270,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 +3283,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 +3298,30 @@ 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 genuine caller cancels — 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.
+        //
+        // Error shape alone cannot identify a caller cancel: NeuroLink's own
+        // watchdog/timeout controllers abort the same composed signal, and SDKs
+        // normalize that into the identical AbortError shapes a user cancel
+        // produces (e.g. Anthropic's APIUserAbortError). Ground truth is the
+        // caller-supplied abortSignal itself — only when IT has fired is an
+        // abort-shaped error a real cancel; otherwise the abort was internally
+        // initiated (turn/stall watchdog, per-step timeout) and the callback
+        // must still be consulted so provider hangs can fall back. Read live
+        // (not captured) so the post-retry re-gate sees a cancel that arrives
+        // mid-fallback; cloneOptionsForCallIsolation keeps abortSignal
+        // by-reference, so the retried options observe the same signal.
+        const callerAborted = () => callOpts.abortSignal?.aborted === true;
+        const shouldOrchestrateFallback = (err) => effectiveCallback
+            ? !(isAbortError(err) && callerAborted())
+            : looksLikeModelAccessDenied(err);
+        if (!shouldOrchestrateFallback(lastError)) {
+            throw lastError;
+        }
         if (!effectiveCallback && !effectiveChain) {
             throw lastError;
         }
@@ -3364,7 +3393,7 @@ Current user's request: ${currentInput}`;
             }
             lastError = retryAttempt.error;
             attemptedRequestedModel = next.model ?? attemptedRequestedModel;
-            if (!looksLikeModelAccessDenied(lastError)) {
+            if (!shouldOrchestrateFallback(lastError)) {
                 throw lastError;
             }
         }
@@ -5223,7 +5252,12 @@ Current user's request: ${currentInput}`;
                         error.isRetryable ===
                             false) ||
                     (error instanceof Error &&
-                        error.statusCode === 400);
+                        error.statusCode === 400) ||
+                    // A 429 already went through the provider layer's bounded,
+                    // Retry-After-aware retry (withProviderRetry) — re-running the
+                    // whole MCP generation against a rate-limited key is redundant
+                    // and only delays fallback orchestration.
+                    getErrorStatusCode(error) === 429;
                 if (isNonRetryable) {
                     logger.debug(`[${functionTag}] Non-retryable error detected, skipping remaining retries`);
                     break;

package/dist/lib/providers/anthropic.js

@@ -608,6 +608,12 @@ export class AnthropicProvider extends BaseProvider {
                 // Note: No headers passed - fetch wrapper sets oauth-2025-04-20 beta header
                 fetch: oauthFetch,
                 timeout: ANTHROPIC_CLIENT_TIMEOUT_MS,
+                // The SDK's built-in retry honors Retry-After hints without any
+                // upper bound (a 429 with retry-after: 8549 sleeps 2.4h per retry,
+                // invisible to fallback orchestration). Retries are the
+                // orchestrator's job; transient network blips are still retried by
+                // the fetch wrapper.
+                maxRetries: 0,
             });
             logger.debug("[AnthropicProvider] Anthropic SDK client created with OAuth fetch wrapper");
             logger.debug("Anthropic Provider initialized with OAuth", {
@@ -654,6 +660,9 @@ export class AnthropicProvider extends BaseProvider {
                 ...(normalizedBaseURL && { baseURL: normalizedBaseURL }),
                 fetch: createProxyFetch(),
                 timeout: ANTHROPIC_CLIENT_TIMEOUT_MS,
+                // See the OAuth-path client above: unbounded Retry-After sleeps in
+                // the SDK's retry loop must never stall fallback orchestration.
+                maxRetries: 0,
             });
             logger.debug("Anthropic Provider initialized with API key", {
                 modelName: this.modelName,
@@ -724,6 +733,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/providers/googleVertex.js

@@ -532,6 +532,10 @@ const createVertexAnthropicSettings = async (region, timeoutMs) => {
         projectId: project,
         region: location,
         ...(timeoutMs !== undefined && { timeout: timeoutMs }),
+        // The SDK's built-in retry honors Retry-After hints without any upper
+        // bound (a 429 with retry-after: 8549 sleeps 2.4h per retry, invisible
+        // to fallback orchestration). Retries are the orchestrator's job.
+        maxRetries: 0,
     };
 };
 // Helper function to determine if a model is an Anthropic model

package/dist/lib/providers/openaiChatCompletionsClient.js

@@ -612,6 +612,15 @@ export const buildAPIError = async (url, body, res) => {
         `OpenAI-compatible request failed with status ${res.status}`;
     const err = new Error(msg);
     err.statusCode = res.status;
+    // Response headers carry rate-limit hints (Retry-After, X-RateLimit-*)
+    // that withProviderRetry needs to honor short waits and surface long ones.
+    // Allowlisted to just those — attaching every header would let unrelated
+    // (potentially sensitive) values like set-cookie or internal routing
+    // headers ride along when the error is logged.
+    err.responseHeaders = Object.fromEntries([...res.headers.entries()].filter(([key]) => {
+        const lower = key.toLowerCase();
+        return lower === "retry-after" || lower.startsWith("x-ratelimit-");
+    }));
     err.url = url;
     // Redacted summary only — never attach raw prompts, tool definitions, or
     // tool arguments to the thrown error. Anything serialized by upstream

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

@@ -27,10 +27,17 @@ 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 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;
@@ -65,16 +72,23 @@ 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
+     * Curator P2-3: callback invoked when a generate/stream call fails with
+     * 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;
     /**
-     * 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,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 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;
@@ -584,7 +589,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/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/lib/types/stream.d.ts

@@ -487,6 +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 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;
@@ -494,7 +500,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/lib/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/lib/utils/providerRetry.js

@@ -24,8 +24,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.
@@ -34,6 +42,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)) {
@@ -43,8 +99,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;
@@ -56,10 +112,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) {
@@ -68,10 +121,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.
@@ -111,10 +166,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/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;