@juspay/neurolink 12.9.0 → 12.9.2

package/dist/cli/commands/proxy.js

@@ -26,7 +26,7 @@ import { ProxyRuntimeConfigStore } from "../../proxy/runtimeConfig.js";
 import { startProxyLogCleanupScheduler } from "../../proxy/logCleanupScheduler.js";
 import { anthropicAccountKeysEqual, createAccountAllowlist, isAccountAllowed, LEGACY_ANTHROPIC_ACCOUNT_KEY, normalizeAnthropicAccountKey, shouldLoadFallbackCredential, } from "../../proxy/accountSelection.js";
 import { resolveProxyStatusAccountIdentity } from "../../proxy/codexAccountUsage.js";
-import { beginProxyRequest, getProxyActivitySnapshot, trackProxyResponse, } from "../../proxy/proxyActivity.js";
+import { beginProxyRequest, getProxyActivitySnapshot, takeProxyResponseObservers, trackProxyResponse, } from "../../proxy/proxyActivity.js";
 import { flushProxyLifecycleEvents, getProxyLifecycleLoggerSnapshot, hashProxyLifecycleSessionId, logProxyLifecycleEvent, } from "../../proxy/proxyLifecycle.js";
 import { describeInstallFailure, getGlobalInstallArgs, isTransientInstallFailure, resolveGlobalInstaller, validateInstalledVersion, } from "../../proxy/globalInstaller.js";
 import { startUpdaterWorkerSupervisor } from "../../proxy/updaterSupervisor.js";
@@ -1120,6 +1120,27 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                 responseStatus,
                 elapsedMs: performance.now() - startedMonotonicMs,
             });
+            const routeResponseObservers = takeProxyResponseObservers(metadata);
+            const notifyRouteFirstChunk = (details) => {
+                for (const observer of routeResponseObservers) {
+                    try {
+                        observer.onFirstChunk?.(details);
+                    }
+                    catch {
+                        // Route-level accounting must never interfere with the relay.
+                    }
+                }
+            };
+            const notifyRouteTerminal = (details) => {
+                for (const observer of routeResponseObservers) {
+                    try {
+                        observer.onTerminal?.(details);
+                    }
+                    catch {
+                        // Route-level accounting must never interfere with the relay.
+                    }
+                }
+            };
             c.res = trackProxyResponse(c.res, finish, {
                 onFirstChunk: ({ observedBodyBytes, responseChunks }) => {
                     logProxyLifecycleEvent({
@@ -1137,6 +1158,10 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                         responseChunks,
                         elapsedMs: performance.now() - startedMonotonicMs,
                     });
+                    notifyRouteFirstChunk({
+                        observedBodyBytes,
+                        responseChunks,
+                    });
                 },
                 onTerminal: ({ outcome, observedBodyBytes, responseChunks }) => {
                     logProxyLifecycleEvent({
@@ -1157,6 +1182,11 @@ function registerProxyRequestTracking(app, requestMetadata, readiness) {
                         errorType: metadata.terminalErrorType,
                         errorCode: metadata.terminalErrorCode,
                     });
+                    notifyRouteTerminal({
+                        outcome,
+                        observedBodyBytes,
+                        responseChunks,
+                    });
                 },
             });
         }
@@ -1484,7 +1514,10 @@ export async function createProxyStartApp(params) {
                 neurolink: params.neurolink,
                 toolRegistry: params.neurolink.getToolRegistry(),
                 timestamp: Date.now(),
-                metadata: {},
+                // Keep route terminal observers on the runtime request metadata so the
+                // outer response tracker can notify them without adding a second body
+                // wrapper to streaming routes.
+                metadata: (metadata ?? {}),
                 // Route handlers publish limit/quota headers here. Only the streaming
                 // paths build their own Response (and set headers directly); every
                 // JSON and error path returns a plain object, so without this the

package/dist/constants/enums.d.ts

@@ -823,17 +823,29 @@ export declare enum CloudflareModels {
     GEMMA_2B_IT_LORA = "@cf/google/gemma-2b-it-lora"
 }
 export declare enum FireworksModels {
+    KIMI_K2P6 = "accounts/fireworks/models/kimi-k2p6",
+    GPT_OSS_120B = "accounts/fireworks/models/gpt-oss-120b",
+    KIMI_K3 = "accounts/fireworks/models/kimi-k3",
+    QWEN3P8_MAX = "accounts/fireworks/models/qwen3p8-max",
+    GLM_5P3 = "accounts/fireworks/models/glm-5p3",
+    MINIMAX_M3 = "accounts/fireworks/models/minimax-m3",
+    DEEPSEEK_V4_FLASH_0731 = "accounts/fireworks/models/deepseek-v4-flash-0731",
     DEEPSEEK_V4_PRO = "accounts/fireworks/models/deepseek-v4-pro",
     GLM_5P1 = "accounts/fireworks/models/glm-5p1",
     GLM_5 = "accounts/fireworks/models/glm-5",
-    KIMI_K2P6 = "accounts/fireworks/models/kimi-k2p6",
     KIMI_K2P5 = "accounts/fireworks/models/kimi-k2p5",
-    GPT_OSS_120B = "accounts/fireworks/models/gpt-oss-120b",
     LLAMA_V3P2_90B_VISION_INSTRUCT = "accounts/fireworks/models/llama-v3p2-90b-vision-instruct",
     LLAMA_V3P2_11B_VISION_INSTRUCT = "accounts/fireworks/models/llama-v3p2-11b-vision-instruct",
     PHI_3_VISION_128K_INSTRUCT = "accounts/fireworks/models/phi-3-vision-128k-instruct"
 }
 export declare enum GroqModels {
+    GPT_OSS_120B = "openai/gpt-oss-120b",
+    GPT_OSS_20B = "openai/gpt-oss-20b",
+    QWEN_3_8_27B = "qwen/qwen3.8-27b",
+    QWEN_3_6_27B = "qwen/qwen3.6-27b",
+    COMPOUND = "groq/compound",
+    COMPOUND_MINI = "groq/compound-mini",
+    ALLAM_2_7B = "allam-2-7b",
     LLAMA_3_3_70B_VERSATILE = "llama-3.3-70b-versatile",
     LLAMA_3_1_8B_INSTANT = "llama-3.1-8b-instant",
     GEMMA_2_9B_IT = "gemma2-9b-it",
@@ -907,6 +919,9 @@ export declare enum TogetherAIModels {
     WIZARDLM_2_8X22B = "microsoft/WizardLM-2-8x22B"
 }
 export declare enum XaiModels {
+    GROK_4_6 = "grok-4.6",
+    GROK_4_5 = "grok-4.5",
+    GROK_4_3 = "grok-4.3",
     GROK_3 = "grok-3",
     GROK_3_MINI = "grok-3-mini",
     GROK_2_LATEST = "grok-2-latest",

package/dist/constants/enums.js

@@ -1074,18 +1074,30 @@ export var CloudflareModels;
 })(CloudflareModels || (CloudflareModels = {}));
 export var FireworksModels;
 (function (FireworksModels) {
+    FireworksModels["KIMI_K2P6"] = "accounts/fireworks/models/kimi-k2p6";
+    FireworksModels["GPT_OSS_120B"] = "accounts/fireworks/models/gpt-oss-120b";
+    FireworksModels["KIMI_K3"] = "accounts/fireworks/models/kimi-k3";
+    FireworksModels["QWEN3P8_MAX"] = "accounts/fireworks/models/qwen3p8-max";
+    FireworksModels["GLM_5P3"] = "accounts/fireworks/models/glm-5p3";
+    FireworksModels["MINIMAX_M3"] = "accounts/fireworks/models/minimax-m3";
+    FireworksModels["DEEPSEEK_V4_FLASH_0731"] = "accounts/fireworks/models/deepseek-v4-flash-0731";
     FireworksModels["DEEPSEEK_V4_PRO"] = "accounts/fireworks/models/deepseek-v4-pro";
     FireworksModels["GLM_5P1"] = "accounts/fireworks/models/glm-5p1";
     FireworksModels["GLM_5"] = "accounts/fireworks/models/glm-5";
-    FireworksModels["KIMI_K2P6"] = "accounts/fireworks/models/kimi-k2p6";
     FireworksModels["KIMI_K2P5"] = "accounts/fireworks/models/kimi-k2p5";
-    FireworksModels["GPT_OSS_120B"] = "accounts/fireworks/models/gpt-oss-120b";
     FireworksModels["LLAMA_V3P2_90B_VISION_INSTRUCT"] = "accounts/fireworks/models/llama-v3p2-90b-vision-instruct";
     FireworksModels["LLAMA_V3P2_11B_VISION_INSTRUCT"] = "accounts/fireworks/models/llama-v3p2-11b-vision-instruct";
     FireworksModels["PHI_3_VISION_128K_INSTRUCT"] = "accounts/fireworks/models/phi-3-vision-128k-instruct";
 })(FireworksModels || (FireworksModels = {}));
 export var GroqModels;
 (function (GroqModels) {
+    GroqModels["GPT_OSS_120B"] = "openai/gpt-oss-120b";
+    GroqModels["GPT_OSS_20B"] = "openai/gpt-oss-20b";
+    GroqModels["QWEN_3_8_27B"] = "qwen/qwen3.8-27b";
+    GroqModels["QWEN_3_6_27B"] = "qwen/qwen3.6-27b";
+    GroqModels["COMPOUND"] = "groq/compound";
+    GroqModels["COMPOUND_MINI"] = "groq/compound-mini";
+    GroqModels["ALLAM_2_7B"] = "allam-2-7b";
     GroqModels["LLAMA_3_3_70B_VERSATILE"] = "llama-3.3-70b-versatile";
     GroqModels["LLAMA_3_1_8B_INSTANT"] = "llama-3.1-8b-instant";
     GroqModels["GEMMA_2_9B_IT"] = "gemma2-9b-it";
@@ -1164,6 +1176,9 @@ export var TogetherAIModels;
 })(TogetherAIModels || (TogetherAIModels = {}));
 export var XaiModels;
 (function (XaiModels) {
+    XaiModels["GROK_4_6"] = "grok-4.6";
+    XaiModels["GROK_4_5"] = "grok-4.5";
+    XaiModels["GROK_4_3"] = "grok-4.3";
     XaiModels["GROK_3"] = "grok-3";
     XaiModels["GROK_3_MINI"] = "grok-3-mini";
     XaiModels["GROK_2_LATEST"] = "grok-2-latest";

package/dist/core/baseProvider.d.ts

@@ -52,6 +52,37 @@ export declare abstract class BaseProvider implements AIProvider {
      * When tools are involved, falls back to generate() with synthetic streaming
      */
     stream(optionsOrPrompt: StreamOptions | string, analysisSchema?: ValidationSchema): Promise<StreamResult>;
+    /**
+     * Swap in a fallback model when a stream dies on a retired id before it has
+     * produced anything.
+     *
+     * OpenAI-compatible streaming is lazy: executeStream() returns a
+     * StreamResult without touching the network, and the request only goes out
+     * on the consumer's first pull. A retired model therefore does NOT fail in
+     * stream()'s try/catch — it fails deep inside iteration. This wrapper sits
+     * UNDER wrapStreamWithLifecycleCallbacks precisely so that a failed first
+     * attempt is invisible: onChunk, onFinish and onError all belong to the
+     * layer above and never observe it.
+     *
+     * The `yielded` guards are the safety property. A stream is only retried
+     * while it has emitted nothing; once a single chunk has reached the
+     * consumer the output is committed, and any later failure propagates
+     * untouched rather than replaying a half-delivered response.
+     */
+    private withStreamModelFallback;
+    /**
+     * The eager half of the retired-model stream fallback, for providers whose
+     * executeStream() reaches the network before returning (see
+     * runGenerateWithModelFallback for the generate() half and the reasoning).
+     *
+     * Returns a working StreamResult when a fallback model succeeds, or
+     * undefined to mean "not recoverable — carry on with the original error".
+     * Returning rather than throwing is deliberate: every existing path in the
+     * caller's catch (the broad fake-streaming fallback, the terminal-error
+     * re-throw, the onError firing) is left exactly as it was, so behaviour
+     * changes only when a fallback actually succeeds.
+     */
+    private retryStreamWithFallbackModel;
     /**
      * Wrap a StreamResult with consumer-facing lifecycle callbacks.
      *
@@ -212,6 +243,31 @@ export declare abstract class BaseProvider implements AIProvider {
      */
     ensureModelLimits(): Promise<void>;
     generate(optionsOrPrompt: TextGenerationOptions | string, _analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
+    /**
+     * Models the catalog names are the models a vendor served when the entry was
+     * last verified. Vendors retire them without warning, and until this existed
+     * the runtime had no answer for that: an InvalidModelError is classified
+     * non-retryable (correctly — another *provider* cannot fix a bad model id),
+     * so the fallback chain stopped dead and the caller got an error even though
+     * the same provider was still serving four other models listed right there
+     * in the catalog's `fallbacks`.
+     *
+     * So on an invalid-model error only, walk this provider's fallbacks. Every
+     * switch is a loud WARN: the caller asked for one model and is getting
+     * another, which they must be able to see in the logs. Any other error type
+     * propagates untouched on the first attempt.
+     *
+     * stream() gets the same treatment via retryStreamWithFallbackModel, which
+     * is safe for the same reason it is cheap: the retry happens before any
+     * lifecycle callback has fired and before a chunk has reached the consumer,
+     * so there is no observable output to replay.
+     */
+    private runGenerateWithModelFallback;
+    /**
+     * Model ids to try when this provider rejects its current model as invalid.
+     * Empty by default; catalog-driven providers return their `fallbacks`.
+     */
+    protected getModelFallbacks(): string[];
     /**
      * Alias for generate method - implements AIProvider interface
      */

package/dist/core/baseProvider.js

@@ -7,7 +7,18 @@ import { modelSupports } from "../models/modelRegistry.js";
 import { resolveRequestKind } from "./resolveRequestKind.js";
 import { ATTR, tracers } from "../telemetry/index.js";
 import { ERROR_CODES, isAbortError, NeuroLinkError, } from "../utils/errorHandling.js";
-import { ProviderError } from "../types/index.js";
+import { InvalidModelError, ProviderError } from "../types/index.js";
+/**
+ * `instanceof` is not reliable here. The published bundle and the source tree
+ * are separate module graphs, so an InvalidModelError built by the error
+ * classifier can fail an `instanceof` against the class this file imported —
+ * silently, with a clean typecheck. The constructor-name check is the same
+ * approach the OTel error-type mapping below already uses.
+ */
+function isInvalidModelError(error) {
+    return (error instanceof InvalidModelError ||
+        (error instanceof Error && error.constructor.name === "InvalidModelError"));
+}
 import { sanitizeErrorCause } from "../utils/logSanitize.js";
 import { createAnalytics as buildAnalytics } from "./analytics.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
@@ -288,9 +299,18 @@ export class BaseProvider {
             // anything that doesn't go through streamText) bypass it. Wrapping
             // here makes the callbacks fire for every provider, regardless of
             // streaming implementation.
-            return this.wrapStreamWithLifecycleCallbacks(realStreamResult, options);
+            return this.wrapStreamWithLifecycleCallbacks(this.withStreamModelFallback(realStreamResult, options, analysisSchema), options);
         }
         catch (realStreamError) {
+            // Retired-model fallback runs FIRST, before any lifecycle callback has
+            // fired and before a single chunk has reached the consumer: onChunk and
+            // onFinish are only wired on the success path above, and onError fires
+            // further down this same catch. That ordering is what makes retrying a
+            // stream safe at all — nothing observable has happened yet.
+            const recovered = await this.retryStreamWithFallbackModel(realStreamError, options, analysisSchema);
+            if (recovered) {
+                return recovered;
+            }
             // The fallback is BROAD, not narrow: only the terminal errors listed
             // below (abort, timeout, 401/403, quota, rate limit, authentication)
             // re-throw. Every other failure — including a genuine configuration or
@@ -337,6 +357,203 @@ export class BaseProvider {
             }
         }
     }
+    /**
+     * Swap in a fallback model when a stream dies on a retired id before it has
+     * produced anything.
+     *
+     * OpenAI-compatible streaming is lazy: executeStream() returns a
+     * StreamResult without touching the network, and the request only goes out
+     * on the consumer's first pull. A retired model therefore does NOT fail in
+     * stream()'s try/catch — it fails deep inside iteration. This wrapper sits
+     * UNDER wrapStreamWithLifecycleCallbacks precisely so that a failed first
+     * attempt is invisible: onChunk, onFinish and onError all belong to the
+     * layer above and never observe it.
+     *
+     * The `yielded` guards are the safety property. A stream is only retried
+     * while it has emitted nothing; once a single chunk has reached the
+     * consumer the output is committed, and any later failure propagates
+     * untouched rather than replaying a half-delivered response.
+     */
+    withStreamModelFallback(result, options, analysisSchema) {
+        // The caller owns fallback order (the Claude proxy sets this): hand the
+        // stream back untouched so an invalid model surfaces as exactly that.
+        if (options.disableInternalFallback === true) {
+            return result;
+        }
+        const provider = this;
+        const source = result.stream;
+        // Iterate through explicit iterators so a consumer break can be forwarded
+        // to the one that is actually in flight (see the cancel hook below): a
+        // generator's own return() is queued behind a pending next(), and a
+        // source that is waiting on a slow vendor would never see the break.
+        const sourceIterator = source[Symbol.asyncIterator]();
+        let activeStream = source;
+        let activeIterator = sourceIterator;
+        const iterableOf = (iterator) => ({
+            [Symbol.asyncIterator]: () => iterator,
+        });
+        // A failing stream still emits one chunk before it throws: the no-output
+        // sentinel, {content: "", metadata: {noOutput: true, ...}}. That is a
+        // marker, not output, so it must not count as committed — otherwise the
+        // guard below blocks every retry it exists to allow. Only that sentinel
+        // and a bare empty text chunk are withheld; everything else — reasoning
+        // deltas ({content: "", reasoning}), tool-call deltas, audio and image
+        // chunks — IS output, commits the stream, and is yielded immediately so
+        // real-time streaming is untouched. Withheld chunks are released in order
+        // once real output arrives, at end of stream, or before any error that is
+        // not retried; they are dropped only when a fallback model takes over.
+        const isWithheld = (chunk) => {
+            if (typeof chunk === "string") {
+                return chunk.length === 0;
+            }
+            if (typeof chunk !== "object" || chunk === null) {
+                return false;
+            }
+            const shape = chunk;
+            if (shape.metadata?.noOutput === true) {
+                return true;
+            }
+            return shape.content === "" && Object.keys(shape).length === 1;
+        };
+        async function* withFallback() {
+            let committed = false;
+            const held = [];
+            try {
+                for await (const chunk of iterableOf(sourceIterator)) {
+                    if (isWithheld(chunk)) {
+                        held.push(chunk);
+                        continue;
+                    }
+                    committed = true;
+                    while (held.length > 0) {
+                        yield held.shift();
+                    }
+                    yield chunk;
+                }
+                while (held.length > 0) {
+                    yield held.shift();
+                }
+                return;
+            }
+            catch (error) {
+                if (committed ||
+                    !isInvalidModelError(provider.formatProviderError(error))) {
+                    // Not retrying: release what was withheld — the sentinel included —
+                    // so the consumer sees exactly what the unwrapped stream produced
+                    // before the error.
+                    while (held.length > 0) {
+                        yield held.shift();
+                    }
+                    throw error;
+                }
+                const requestedModel = provider.modelName;
+                const candidates = provider
+                    .getModelFallbacks()
+                    .filter((model) => model !== requestedModel);
+                for (const candidate of candidates) {
+                    logger.warn(`[${provider.providerName}] model "${requestedModel}" was rejected as invalid — retrying stream with fallback "${candidate}". This provider's catalog entry is stale; run "pnpm run check:models".`);
+                    provider.refreshHandlersForModel(candidate);
+                    let retryCommitted = false;
+                    const retryHeld = [];
+                    try {
+                        const retry = await provider.executeStream(options, analysisSchema);
+                        const retryIterator = retry.stream[Symbol.asyncIterator]();
+                        activeStream = retry.stream;
+                        activeIterator = retryIterator;
+                        for await (const chunk of iterableOf(retryIterator)) {
+                            if (isWithheld(chunk)) {
+                                retryHeld.push(chunk);
+                                continue;
+                            }
+                            retryCommitted = true;
+                            while (retryHeld.length > 0) {
+                                yield retryHeld.shift();
+                            }
+                            yield chunk;
+                        }
+                        while (retryHeld.length > 0) {
+                            yield retryHeld.shift();
+                        }
+                        return;
+                    }
+                    catch (retryError) {
+                        // Same rule as above: once this candidate has emitted real
+                        // content its output is committed, and moving to another model
+                        // would splice two different responses together.
+                        if (retryCommitted) {
+                            throw retryError;
+                        }
+                    }
+                }
+                provider.refreshHandlersForModel(requestedModel);
+                // Every fallback failed too: release the original attempt's withheld
+                // chunks, then surface the ORIGINAL error — it names the model the
+                // caller asked for.
+                while (held.length > 0) {
+                    yield held.shift();
+                }
+                throw error;
+            }
+        }
+        const wrapped = withFallback();
+        // Same contract as wrapStreamWithLifecycleCallbacks: a consumer break
+        // (cancelStream on the outer stream) must close the live upstream
+        // iterator directly, not wait for this generator to reach its next
+        // yield. Without this, the TTS early-break path — and any consumer that
+        // stops mid-stream — would leave the vendor request open until the next
+        // chunk arrived.
+        attachStreamCancel(wrapped, () => {
+            cancelStream(activeStream);
+            releaseIterator(activeIterator);
+        });
+        return {
+            ...result,
+            stream: wrapped,
+        };
+    }
+    /**
+     * The eager half of the retired-model stream fallback, for providers whose
+     * executeStream() reaches the network before returning (see
+     * runGenerateWithModelFallback for the generate() half and the reasoning).
+     *
+     * Returns a working StreamResult when a fallback model succeeds, or
+     * undefined to mean "not recoverable — carry on with the original error".
+     * Returning rather than throwing is deliberate: every existing path in the
+     * caller's catch (the broad fake-streaming fallback, the terminal-error
+     * re-throw, the onError firing) is left exactly as it was, so behaviour
+     * changes only when a fallback actually succeeds.
+     */
+    async retryStreamWithFallbackModel(error, options, analysisSchema) {
+        if (options.disableInternalFallback === true) {
+            return undefined;
+        }
+        // executeStream() surfaces the raw transport error, so classify it the
+        // way this provider would before deciding. formatProviderError is
+        // contractually return-only, never throw.
+        if (!isInvalidModelError(this.formatProviderError(error))) {
+            return undefined;
+        }
+        const requestedModel = this.modelName;
+        const candidates = this.getModelFallbacks().filter((model) => model !== requestedModel);
+        for (const candidate of candidates) {
+            logger.warn(`[${this.providerName}] model "${requestedModel}" was rejected as invalid — retrying stream with fallback "${candidate}". This provider's catalog entry is stale; run "pnpm run check:models".`);
+            this.refreshHandlersForModel(candidate);
+            try {
+                const result = await this.executeStream(options, analysisSchema);
+                return this.wrapStreamWithLifecycleCallbacks(result, options);
+            }
+            catch {
+                // Any failure on a candidate — stale id or otherwise — just moves to
+                // the next one. Nothing is reported from here: if none succeed the
+                // caller still handles the ORIGINAL error, which names the model the
+                // caller actually asked for.
+            }
+        }
+        // Restore the caller's model so a failed request does not leave this
+        // instance silently pointing at the last fallback it tried.
+        this.refreshHandlersForModel(requestedModel);
+        return undefined;
+    }
     /**
      * Wrap a StreamResult with consumer-facing lifecycle callbacks.
      *
@@ -1061,21 +1278,95 @@ export class BaseProvider {
         const options = this.normalizeTextOptions(optionsOrPrompt);
         this.validateOptions(options);
         const startTime = Date.now();
-        // OTEL span for provider-level generate tracing
-        // Use startActiveSpan pattern via context.with() so child spans become descendants
-        const otelSpan = tracers.provider.startSpan("neurolink.provider.generate", {
-            kind: SpanKind.CLIENT,
-            attributes: {
-                [ATTR.GEN_AI_SYSTEM]: this.providerName || "unknown",
-                [ATTR.GEN_AI_MODEL]: this.modelName || options.model || "unknown",
-                [ATTR.GEN_AI_OPERATION]: "generate",
-                [ATTR.NL_PROVIDER]: this.providerName || "unknown",
-            },
-        });
-        // Set this span as the active context so child spans (GenerationHandler, etc.) become descendants
-        const activeCtx = trace.setSpan(context.active(), otelSpan);
-        const otelSpanState = { ended: false };
-        return await context.with(activeCtx, async () => this.runGenerateInActiveContext(options, startTime, otelSpan, otelSpanState));
+        // One span per attempt. runGenerateInActiveContext ends the span on the
+        // way out (success or failure), so a model-fallback retry must not reuse
+        // it — an ended span would swallow the retry's attributes and report the
+        // model that failed rather than the one that served.
+        const attempt = async () => {
+            // OTEL span for provider-level generate tracing
+            // Use startActiveSpan pattern via context.with() so child spans become descendants
+            const otelSpan = tracers.provider.startSpan("neurolink.provider.generate", {
+                kind: SpanKind.CLIENT,
+                attributes: {
+                    [ATTR.GEN_AI_SYSTEM]: this.providerName || "unknown",
+                    [ATTR.GEN_AI_MODEL]: this.modelName || options.model || "unknown",
+                    [ATTR.GEN_AI_OPERATION]: "generate",
+                    [ATTR.NL_PROVIDER]: this.providerName || "unknown",
+                },
+            });
+            // Set this span as the active context so child spans (GenerationHandler, etc.) become descendants
+            const activeCtx = trace.setSpan(context.active(), otelSpan);
+            const otelSpanState = { ended: false };
+            return await context.with(activeCtx, async () => this.runGenerateInActiveContext(options, startTime, otelSpan, otelSpanState));
+        };
+        // TextGenerationOptions does not declare the flag (it lives on
+        // StreamOptions), but callers that own fallback order pass it on both
+        // paths, so honour it here as well.
+        const callerOwnsFallback = "disableInternalFallback" in options &&
+            options.disableInternalFallback === true;
+        return await this.runGenerateWithModelFallback(attempt, callerOwnsFallback);
+    }
+    /**
+     * Models the catalog names are the models a vendor served when the entry was
+     * last verified. Vendors retire them without warning, and until this existed
+     * the runtime had no answer for that: an InvalidModelError is classified
+     * non-retryable (correctly — another *provider* cannot fix a bad model id),
+     * so the fallback chain stopped dead and the caller got an error even though
+     * the same provider was still serving four other models listed right there
+     * in the catalog's `fallbacks`.
+     *
+     * So on an invalid-model error only, walk this provider's fallbacks. Every
+     * switch is a loud WARN: the caller asked for one model and is getting
+     * another, which they must be able to see in the logs. Any other error type
+     * propagates untouched on the first attempt.
+     *
+     * stream() gets the same treatment via retryStreamWithFallbackModel, which
+     * is safe for the same reason it is cheap: the retry happens before any
+     * lifecycle callback has fired and before a chunk has reached the consumer,
+     * so there is no observable output to replay.
+     */
+    async runGenerateWithModelFallback(attempt, callerOwnsFallback) {
+        const requestedModel = this.modelName;
+        try {
+            return await attempt();
+        }
+        catch (error) {
+            if (callerOwnsFallback || !isInvalidModelError(error)) {
+                throw error;
+            }
+            const candidates = this.getModelFallbacks().filter((model) => model !== requestedModel);
+            if (candidates.length === 0) {
+                throw error;
+            }
+            for (const candidate of candidates) {
+                logger.warn(`[${this.providerName}] model "${requestedModel}" was rejected as invalid — retrying with fallback "${candidate}". This provider's catalog entry is stale; run "pnpm run check:models".`);
+                this.refreshHandlersForModel(candidate);
+                try {
+                    return await attempt();
+                }
+                catch (retryError) {
+                    if (!isInvalidModelError(retryError)) {
+                        // Restore the caller's model: this failure is unrelated to the
+                        // model id, so the instance must not be left on a fallback.
+                        this.refreshHandlersForModel(requestedModel);
+                        throw retryError;
+                    }
+                    // This fallback is stale too — keep walking the list.
+                }
+            }
+            // Every fallback was rejected as well. Restore the caller's model so a
+            // failed request does not leave this instance silently repointed, and
+            // surface the ORIGINAL error: it names the model the caller asked for.
+            this.refreshHandlersForModel(requestedModel);
+            throw error;
+        }
+    }
+    /**
+     * Model ids to try when this provider rejects its current model as invalid.
+     * Empty by default; catalog-driven providers return their `fallbacks`.
+     */
+    getModelFallbacks() {
+        return [];
     }
     /**
      * Alias for generate method - implements AIProvider interface

package/dist/providers/catalog/cerebras.json

@@ -15,19 +15,26 @@
         "catalog": {
             "gpt-oss-120b": {
                 "contextWindow": 65536,
-                "pricingPerMTok": { "input": 0.35, "output": 0.75 },
+                "pricingPerMTok": {
+                    "input": 0.35,
+                    "output": 0.75
+                },
                 "vision": false,
                 "status": "production",
                 "description": "Recommended - OpenAI GPT-OSS 120B (open-weight); wafer-scale speed"
             },
             "gemma-4-31b": {
                 "contextWindow": 65536,
-                "pricingPerMTok": { "input": 0.99, "output": 1.49 },
-                "vision": false,
+                "pricingPerMTok": {
+                    "input": 0.99,
+                    "output": 1.49
+                },
+                "vision": true,
                 "status": "production",
-                "description": "Google Gemma 4 31B"
+                "description": "Google Gemma 4 31B — vision-capable"
             }
         },
+        "visionModel": "gemma-4-31b",
         "topModels": ["gpt-oss-120b", "gemma-4-31b"]
     },
     "capabilities": {
@@ -69,7 +76,10 @@
             "status": 401,
             "code": "wrong_api_key"
         },
-        "liveMatrix": { "date": "2026-08-27", "result": "4/4" },
+        "liveMatrix": {
+            "date": "2026-08-30",
+            "result": "Both ids answer. Vision re-tested with a valid 64x64 PNG: gemma-4-31b describes it correctly, so its vision flag is now true (it was false); gpt-oss-120b answers \"Content type 'image_url' is not supported by selected model\"."
+        },
         "addedInPR": "https://github.com/juspay/neurolink/pull/1561"
     }
 }