@juspay/neurolink 9.57.1 → 9.59.0

package/dist/lib/types/errors.js

@@ -165,4 +165,98 @@ export class ModelAccessError extends BaseError {
         this.requiredTier = requiredTier;
     }
 }
+/**
+ * Curator P1-1: thrown when a provider rejects a request because the
+ * caller's team / API key is not whitelisted for the requested model.
+ *
+ * LiteLLM's `team not allowed to access model. This team can only access
+ * models=['glm-latest', 'kimi-latest', ...]` is the canonical example —
+ * the list is parsed off the error body so callers / fallback orchestrators
+ * can choose a whitelisted alternative without scraping strings.
+ */
+export class ModelAccessDeniedError extends ProviderError {
+    requestedModel;
+    allowedModels;
+    code = "MODEL_ACCESS_DENIED";
+    constructor(message, options = {}) {
+        super(message, options.provider);
+        this.name = "ModelAccessDeniedError";
+        this.requestedModel = options.requestedModel;
+        this.allowedModels = options.allowedModels;
+    }
+}
+/** Maximum body length we'll attempt to parse. Real provider error
+ *  bodies are well under 10 KB; longer inputs are either truncated
+ *  log output or a deliberate ReDoS attempt. */
+const MAX_ALLOWED_MODELS_INPUT = 10_000;
+/**
+ * Parse the `allowed_models` array out of a provider error message body.
+ * Currently targets the LiteLLM team-whitelist response shape:
+ *
+ *   "team not allowed to access model. This team can only access
+ *    models=['glm-latest', 'kimi-latest', 'open-large']"
+ *
+ * Implementation note: deliberately uses `indexOf`/`slice` instead of a
+ * single `/models\s*=\s*\[([^\]]*)\]/` regex. CodeQL flagged the latter
+ * as `js/polynomial-redos` because the `[^\]]*` greedy quantifier on
+ * library-supplied input can be exploited by a crafted long string. The
+ * indexOf/slice path is O(n) with no backtracking and we additionally
+ * cap the input length.
+ *
+ * Returns undefined when no list is found.
+ */
+export function parseAllowedModels(message) {
+    if (typeof message !== "string" || message.length === 0) {
+        return undefined;
+    }
+    if (message.length > MAX_ALLOWED_MODELS_INPUT) {
+        return undefined;
+    }
+    // Locate `models` keyword case-insensitively, then walk forward to
+    // confirm `=` and `[` markers — no regex backtracking.
+    const lower = message.toLowerCase();
+    let idx = lower.indexOf("models", 0);
+    while (idx !== -1) {
+        let cursor = idx + "models".length;
+        // Skip whitespace
+        while (cursor < message.length && /\s/.test(message[cursor])) {
+            cursor++;
+        }
+        if (message[cursor] !== "=") {
+            idx = lower.indexOf("models", idx + 1);
+            continue;
+        }
+        cursor++;
+        while (cursor < message.length && /\s/.test(message[cursor])) {
+            cursor++;
+        }
+        if (message[cursor] !== "[") {
+            idx = lower.indexOf("models", idx + 1);
+            continue;
+        }
+        const open = cursor;
+        const close = message.indexOf("]", open + 1);
+        if (close === -1) {
+            return undefined;
+        }
+        const inside = message.slice(open + 1, close);
+        const items = inside
+            .split(",")
+            .map((s) => s.trim().replace(/^['"]|['"]$/g, ""))
+            .filter((s) => s.length > 0);
+        return items.length > 0 ? items : undefined;
+    }
+    return undefined;
+}
+/**
+ * Returns true when `message` looks like a model-access-denied response
+ * (LiteLLM "team not allowed", generic "not allowed to access model",
+ * or "team can only access models=[...]").
+ */
+export function isModelAccessDeniedMessage(message) {
+    const lower = message.toLowerCase();
+    return ((lower.includes("team") && lower.includes("not allowed")) ||
+        lower.includes("team can only access") ||
+        /not\s+allowed\s+to\s+access\s+(this\s+)?model/i.test(message));
+}
 //# sourceMappingURL=errors.js.map

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

@@ -447,6 +447,19 @@ export type GenerateOptions = {
      * Unset providers fall through to instance credentials, then environment variables.
      */
     credentials?: NeurolinkCredentials;
+    /**
+     * Curator P2-3: per-call fallback callback. Overrides any
+     * instance-level `providerFallback` set on `new NeuroLink({...})`.
+     */
+    providerFallback?: (error: unknown) => Promise<{
+        provider?: string;
+        model?: string;
+    } | null>;
+    /**
+     * Curator P2-3: per-call ordered model chain. Overrides any
+     * instance-level `modelChain`. Tried in order on model-access-denied.
+     */
+    modelChain?: string[];
     /**
      * Per-call memory control.
      *

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

@@ -445,6 +445,19 @@ export type StreamOptions = {
      * Unset providers fall through to instance credentials, then environment variables.
      */
     credentials?: NeurolinkCredentials;
+    /**
+     * Curator P2-3: per-call fallback callback. Overrides any
+     * instance-level `providerFallback` set on `new NeuroLink({...})`.
+     */
+    providerFallback?: (error: unknown) => Promise<{
+        provider?: string;
+        model?: string;
+    } | null>;
+    /**
+     * Curator P2-3: per-call ordered model chain. Overrides any
+     * instance-level `modelChain`. Tried in order on model-access-denied.
+     */
+    modelChain?: string[];
     /**
      * Per-call memory control.
      *

package/dist/neurolink.d.ts

@@ -60,6 +60,7 @@ export declare class NeuroLink {
     private pendingAuthConfig?;
     private authInitPromise?;
     private credentials?;
+    private readonly fallbackConfig;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -541,6 +542,21 @@ export declare class NeuroLink {
      * @since 1.0.0
      */
     generate(optionsOrPrompt: GenerateOptions | DynamicOptions | string): Promise<GenerateResult>;
+    /**
+     * 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:
+     *  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
+     *     `model.fallback` event → re-call inner with the new {provider,
+     *     model}.
+     *  3. Stop on first success, on a callback returning null, or after
+     *     exhausting the chain (throw the most recent error).
+     */
+    private runWithFallbackOrchestration;
+    private attemptInner;
     private executeGenerateWithMetricsContext;
     private executeGenerateRequest;
     private prepareGenerateRequest;
@@ -697,6 +713,25 @@ export declare class NeuroLink {
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
     stream(options: StreamOptions | DynamicOptions): Promise<StreamResult>;
+    /**
+     * Curator P2-3 / Reviewer Finding #2: stream-fallback that also covers
+     * errors thrown during async iteration (e.g. LiteLLM throwing inside
+     * `createLiteLLMTransformedStream`). The standard
+     * `runWithFallbackOrchestration` only catches errors thrown while the
+     * `StreamResult` is being created — once we hand the iterator back to
+     * the caller, errors raised during consumption used to bypass
+     * `providerFallback` / `modelChain`.
+     *
+     * This wrapper runs the orchestration to get an initial StreamResult,
+     * then wraps `result.stream` so that:
+     *   - chunks are forwarded transparently while consumption succeeds
+     *   - if iteration throws a model-access-denied error AND no chunks
+     *     have been yielded yet, we resolve the next fallback target,
+     *     emit `model.fallback`, and recurse
+     *   - if chunks were already yielded, the error propagates (mid-stream
+     *     recovery isn't safe — the consumer has half a response)
+     */
+    private streamWithIterationFallback;
     private executeStreamRequest;
     private validateStreamRequestOptions;
     private maybeHandleWorkflowStreamRequest;
@@ -933,6 +968,40 @@ export declare class NeuroLink {
      * @see {@link NeuroLink.executeTool} for events related to tool execution
      */
     getEventEmitter(): TypedEventEmitter<NeuroLinkEvents>;
+    /**
+     * Curator P1-1: synchronous credential health check for a single provider.
+     *
+     * Drives a tiny real call against the provider (1-token completion or
+     * `/models` listing depending on provider) to confirm the configured
+     * credentials are valid. Useful at startup so a service can refuse to
+     * boot if its primary provider's credentials are broken instead of
+     * discovering the problem on first user request.
+     *
+     * @example
+     * ```ts
+     * const health = await neurolink.checkCredentials({ provider: "litellm" });
+     * if (health.status !== "ok") {
+     *   throw new Error(`provider not ready: ${health.detail}`);
+     * }
+     * ```
+     *
+     * @param input - the provider to check
+     * @returns `{ provider, status, detail }`. Possible status values:
+     *   - `"ok"` — credentials valid and provider reachable
+     *   - `"missing"` — required env / credentials not configured
+     *   - `"expired"` — credentials present but rejected (401/403)
+     *   - `"denied"` — credentials valid but team not whitelisted for any model
+     *   - `"network"` — provider unreachable (timeout, ECONNREFUSED, DNS)
+     *   - `"unknown"` — other error; consult `detail`
+     */
+    checkCredentials(input: {
+        provider: string;
+        model?: string;
+    }): Promise<{
+        provider: string;
+        status: "ok" | "missing" | "expired" | "denied" | "network" | "unknown";
+        detail: string;
+    }>;
     /**
      * Emit tool start event with execution tracking
      * @param toolName - Name of the tool being executed

package/dist/neurolink.js

@@ -52,7 +52,7 @@ import { resolveDynamicArgument } from "./dynamic/dynamicResolver.js";
 import { initializeHippocampus } from "./memory/hippocampusInitializer.js";
 import { createMemoryRetrievalTools } from "./memory/memoryRetrievalTools.js";
 import { getMetricsAggregator, MetricsAggregator, } from "./observability/metricsAggregator.js";
-import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, AuthenticationError, AuthorizationError, InvalidModelError, } from "./types/index.js";
+import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, AuthenticationError, AuthorizationError, InvalidModelError, ModelAccessDeniedError, } from "./types/index.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { flushOpenTelemetry, getLangfuseHealthStatus, initializeOpenTelemetry, isOpenTelemetryInitialized, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
 import { TaskManager } from "./tasks/taskManager.js";
@@ -146,6 +146,36 @@ function mcpCategoryToErrorCategory(mcpCategory) {
  * For example, a NOT_FOUND error for a model causes 6 retries of a 418KB
  * message, wasting ~628,000 tokens and adding 10+ seconds of latency.
  */
+/**
+ * Curator P2-3: detect model-access-denied without requiring the typed
+ * ModelAccessDeniedError class to be present (Issue #1 ships that class
+ * separately). Matches LiteLLM "team not allowed" / "team can only access
+ * models=[...]" plus typed-error markers when present.
+ */
+function looksLikeModelAccessDenied(error) {
+    if (!error) {
+        return false;
+    }
+    const e = error;
+    if (e.name === "ModelAccessDeniedError") {
+        return true;
+    }
+    if (e.code === "MODEL_ACCESS_DENIED") {
+        return true;
+    }
+    const msg = typeof e.message === "string"
+        ? e.message
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    if (!msg) {
+        return false;
+    }
+    const lower = msg.toLowerCase();
+    return ((lower.includes("team") && lower.includes("not allowed")) ||
+        lower.includes("team can only access") ||
+        /not\s+allowed\s+to\s+access\s+(this\s+)?model/i.test(msg));
+}
 function isNonRetryableProviderError(error) {
     // Check for typed error classes from providers
     if (error instanceof InvalidModelError) {
@@ -157,6 +187,13 @@ function isNonRetryableProviderError(error) {
     if (error instanceof AuthorizationError) {
         return true;
     }
+    // Curator P1-1: model-access-denied is permanent for the (provider, model)
+    // pair until the team whitelist changes. Retrying with the same config
+    // would just waste a second roundtrip. Caller / fallback-orchestrator
+    // should pick a different model.
+    if (error instanceof ModelAccessDeniedError) {
+        return true;
+    }
     // Check for HTTP status codes on error objects (e.g., from Vercel AI SDK)
     if (error && typeof error === "object") {
         const err = error;
@@ -334,6 +371,9 @@ export class NeuroLink {
     authInitPromise;
     // Per-provider credential overrides (instance-level default)
     credentials;
+    // Curator P2-3: instance-level fallback policy. Read by
+    // runWithFallbackOrchestration on model-access-denied.
+    fallbackConfig = {};
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -721,6 +761,14 @@ export class NeuroLink {
         if (config?.modelAliasConfig) {
             this.modelAliasConfig = config.modelAliasConfig;
         }
+        // Curator P2-3: capture fallback policy. Per-call options can still
+        // override, but these are the instance-level defaults.
+        if (config?.providerFallback) {
+            this.fallbackConfig.providerFallback = config.providerFallback;
+        }
+        if (config?.modelChain) {
+            this.fallbackConfig.modelChain = config.modelChain;
+        }
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
@@ -2669,7 +2717,121 @@ Current user's request: ${currentInput}`;
      * @since 1.0.0
      */
     async generate(optionsOrPrompt) {
-        return tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(optionsOrPrompt, generateSpan));
+        return this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(opts, generateSpan)));
+    }
+    /**
+     * 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:
+     *  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
+     *     `model.fallback` event → re-call inner with the new {provider,
+     *     model}.
+     *  3. Stop on first success, on a callback returning null, or after
+     *     exhausting the chain (throw the most recent error).
+     */
+    async runWithFallbackOrchestration(optionsOrPrompt, kind, inner) {
+        const initialAttempt = await this.attemptInner(inner, optionsOrPrompt);
+        if ("ok" in initialAttempt) {
+            return initialAttempt.ok;
+        }
+        let lastError = initialAttempt.error;
+        if (!looksLikeModelAccessDenied(lastError)) {
+            throw lastError;
+        }
+        // Build the chain orchestration.
+        const requestedProvider = (typeof optionsOrPrompt === "object"
+            ? optionsOrPrompt.provider
+            : undefined);
+        const requestedModel = (typeof optionsOrPrompt === "object"
+            ? optionsOrPrompt.model
+            : undefined);
+        const callOpts = typeof optionsOrPrompt === "object"
+            ? optionsOrPrompt
+            : {};
+        const perCallCallback = callOpts.providerFallback;
+        const perCallChain = callOpts.modelChain;
+        const effectiveCallback = perCallCallback ?? this.fallbackConfig.providerFallback;
+        const effectiveChain = perCallChain ?? this.fallbackConfig.modelChain;
+        if (!effectiveCallback && !effectiveChain) {
+            throw lastError;
+        }
+        // Synthesise a callback from modelChain if no explicit callback exists.
+        const chainCursor = { i: 0, list: effectiveChain ?? [] };
+        const synthesizedFromChain = async () => {
+            while (chainCursor.i < chainCursor.list.length) {
+                const next = chainCursor.list[chainCursor.i++];
+                if (next !== requestedModel) {
+                    return { model: next };
+                }
+            }
+            return null;
+        };
+        const callback = effectiveCallback ?? synthesizedFromChain;
+        let attempts = 0;
+        const maxAttempts = (effectiveChain?.length ?? 0) + 5;
+        let attemptedRequestedModel = requestedModel;
+        while (attempts++ < maxAttempts) {
+            let next;
+            try {
+                next = await callback(lastError);
+            }
+            catch (cbErr) {
+                logger.warn("[NeuroLink] providerFallback callback threw", {
+                    error: cbErr instanceof Error ? cbErr.message : String(cbErr),
+                });
+                throw lastError;
+            }
+            if (!next) {
+                throw lastError;
+            }
+            // Emit model.fallback event so cost/audit listeners can record it.
+            try {
+                this.emitter.emit("model.fallback", {
+                    requestedProvider,
+                    requestedModel: attemptedRequestedModel,
+                    fallbackProvider: next.provider ?? requestedProvider,
+                    fallbackModel: next.model,
+                    reason: lastError instanceof Error ? lastError.message : String(lastError),
+                    kind,
+                    timestamp: Date.now(),
+                });
+            }
+            catch {
+                /* listener errors are non-fatal */
+            }
+            const retriedOptions = typeof optionsOrPrompt === "object"
+                ? {
+                    ...optionsOrPrompt,
+                    ...(next.provider && { provider: next.provider }),
+                    ...(next.model && { model: next.model }),
+                    // Strip the fallback hooks so the retry doesn't re-orchestrate.
+                    providerFallback: undefined,
+                    modelChain: undefined,
+                }
+                : optionsOrPrompt;
+            const retryAttempt = await this.attemptInner(inner, retriedOptions);
+            if ("ok" in retryAttempt) {
+                return retryAttempt.ok;
+            }
+            lastError = retryAttempt.error;
+            attemptedRequestedModel = next.model ?? attemptedRequestedModel;
+            if (!looksLikeModelAccessDenied(lastError)) {
+                throw lastError;
+            }
+        }
+        throw lastError;
+    }
+    async attemptInner(inner, options) {
+        try {
+            const ok = await inner(options);
+            return { ok };
+        }
+        catch (error) {
+            return { error };
+        }
     }
     async executeGenerateWithMetricsContext(optionsOrPrompt, generateSpan) {
         return metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeGenerateRequest(optionsOrPrompt, generateSpan));
@@ -4566,7 +4728,128 @@ Current user's request: ${currentInput}`;
                 : [],
             optionKeys: Object.keys(options),
         });
-        return metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeStreamRequest({ ...options }));
+        return this.streamWithIterationFallback(options);
+    }
+    /**
+     * Curator P2-3 / Reviewer Finding #2: stream-fallback that also covers
+     * errors thrown during async iteration (e.g. LiteLLM throwing inside
+     * `createLiteLLMTransformedStream`). The standard
+     * `runWithFallbackOrchestration` only catches errors thrown while the
+     * `StreamResult` is being created — once we hand the iterator back to
+     * the caller, errors raised during consumption used to bypass
+     * `providerFallback` / `modelChain`.
+     *
+     * This wrapper runs the orchestration to get an initial StreamResult,
+     * then wraps `result.stream` so that:
+     *   - chunks are forwarded transparently while consumption succeeds
+     *   - if iteration throws a model-access-denied error AND no chunks
+     *     have been yielded yet, we resolve the next fallback target,
+     *     emit `model.fallback`, and recurse
+     *   - if chunks were already yielded, the error propagates (mid-stream
+     *     recovery isn't safe — the consumer has half a response)
+     */
+    async streamWithIterationFallback(options) {
+        const result = await this.runWithFallbackOrchestration(options, "stream", (opts) => metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeStreamRequest({ ...opts })));
+        const callOpts = options;
+        const perCallCallback = callOpts.providerFallback;
+        const perCallChain = callOpts.modelChain;
+        const effectiveCallback = perCallCallback ?? this.fallbackConfig.providerFallback;
+        const effectiveChain = perCallChain ?? this.fallbackConfig.modelChain;
+        if (!effectiveCallback && !effectiveChain) {
+            // No fallback configured — nothing to wrap.
+            return result;
+        }
+        // Build a chain cursor scoped to this stream's lifetime; consumers
+        // who set up `modelChain` get sequential progression here too.
+        const chainCursor = {
+            i: 0,
+            list: effectiveChain ?? [],
+            requestedModel: options.model,
+        };
+        const callback = effectiveCallback ??
+            (async () => {
+                while (chainCursor.i < chainCursor.list.length) {
+                    const next = chainCursor.list[chainCursor.i++];
+                    if (next !== chainCursor.requestedModel) {
+                        return { model: next };
+                    }
+                }
+                return null;
+            });
+        const self = this;
+        // Yield type is the original stream's element type, threaded through
+        // as unknown — we forward chunks unchanged so structural identity is
+        // preserved without a local type alias (CLAUDE.md rule 2).
+        const wrappedStream = (async function* () {
+            let yielded = 0;
+            let currentResult = result;
+            let attemptedRequestedProvider = options.provider;
+            let attemptedRequestedModel = options.model;
+            const maxAttempts = (effectiveChain?.length ?? 0) + 5;
+            for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+                try {
+                    for await (const chunk of currentResult.stream) {
+                        yielded++;
+                        yield chunk;
+                    }
+                    return;
+                }
+                catch (err) {
+                    if (yielded > 0 || !looksLikeModelAccessDenied(err)) {
+                        throw err;
+                    }
+                    let next;
+                    try {
+                        next = await callback(err);
+                    }
+                    catch (cbErr) {
+                        logger.warn("[NeuroLink.stream] providerFallback callback threw during iteration", {
+                            error: cbErr instanceof Error ? cbErr.message : String(cbErr),
+                        });
+                        throw err;
+                    }
+                    if (!next) {
+                        throw err;
+                    }
+                    try {
+                        self.emitter.emit("model.fallback", {
+                            requestedProvider: attemptedRequestedProvider,
+                            requestedModel: attemptedRequestedModel,
+                            fallbackProvider: next.provider ?? attemptedRequestedProvider,
+                            fallbackModel: next.model,
+                            reason: err instanceof Error ? err.message : String(err),
+                            kind: "stream",
+                            phase: "iteration",
+                            timestamp: Date.now(),
+                        });
+                    }
+                    catch {
+                        /* listener errors are non-fatal */
+                    }
+                    const retriedOptions = {
+                        ...options,
+                        ...(next.provider && {
+                            provider: next.provider,
+                        }),
+                        ...(next.model && { model: next.model }),
+                        // Strip the hooks so the inner orchestration doesn't double-fall-back.
+                        providerFallback: undefined,
+                        modelChain: undefined,
+                    };
+                    attemptedRequestedProvider =
+                        next.provider ?? attemptedRequestedProvider;
+                    attemptedRequestedModel = next.model ?? attemptedRequestedModel;
+                    currentResult = await metricsTraceContextStorage.run(self.createMetricsTraceContext(), () => self.executeStreamRequest({ ...retriedOptions }));
+                }
+            }
+            // Exhausted attempts — re-throw the most recent error captured by
+            // the inner loop. We only get here if the loop didn't return.
+            throw new Error(`[NeuroLink.stream] iteration fallback exhausted ${maxAttempts} attempts`);
+        })();
+        return {
+            ...result,
+            stream: wrappedStream,
+        };
     }
     async executeStreamRequest(options) {
         // Dynamic argument resolution — resolve any function-valued options before downstream use
@@ -5811,6 +6094,87 @@ Current user's request: ${currentInput}`;
     getEventEmitter() {
         return this.emitter;
     }
+    /**
+     * Curator P1-1: synchronous credential health check for a single provider.
+     *
+     * Drives a tiny real call against the provider (1-token completion or
+     * `/models` listing depending on provider) to confirm the configured
+     * credentials are valid. Useful at startup so a service can refuse to
+     * boot if its primary provider's credentials are broken instead of
+     * discovering the problem on first user request.
+     *
+     * @example
+     * ```ts
+     * const health = await neurolink.checkCredentials({ provider: "litellm" });
+     * if (health.status !== "ok") {
+     *   throw new Error(`provider not ready: ${health.detail}`);
+     * }
+     * ```
+     *
+     * @param input - the provider to check
+     * @returns `{ provider, status, detail }`. Possible status values:
+     *   - `"ok"` — credentials valid and provider reachable
+     *   - `"missing"` — required env / credentials not configured
+     *   - `"expired"` — credentials present but rejected (401/403)
+     *   - `"denied"` — credentials valid but team not whitelisted for any model
+     *   - `"network"` — provider unreachable (timeout, ECONNREFUSED, DNS)
+     *   - `"unknown"` — other error; consult `detail`
+     */
+    async checkCredentials(input) {
+        const { provider, model } = input;
+        const probeText = "ping";
+        try {
+            // 1-token probe is cheap, exercises auth + routing without much cost.
+            await this.generate({
+                provider: provider,
+                ...(model && { model }),
+                input: { text: probeText },
+                maxTokens: 16,
+                disableTools: true,
+            });
+            return { provider, status: "ok", detail: "credentials valid" };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            const lower = msg.toLowerCase();
+            if (err instanceof ModelAccessDeniedError) {
+                return {
+                    provider,
+                    status: "denied",
+                    detail: msg,
+                };
+            }
+            if (lower.includes("authentication") ||
+                lower.includes("401") ||
+                lower.includes("invalid api key") ||
+                lower.includes("incorrect api key") ||
+                lower.includes("api_key_invalid") ||
+                lower.includes("token has expired") ||
+                lower.includes("expired credentials")) {
+                return { provider, status: "expired", detail: msg };
+            }
+            if (lower.includes("not configured") ||
+                lower.includes("missing api") ||
+                lower.includes("api key is required") ||
+                lower.includes("no api key") ||
+                lower.includes("application default credentials") ||
+                lower.includes("google_application_credentials") ||
+                lower.includes("project_id") ||
+                lower.includes("default credentials") ||
+                lower.includes("service account")) {
+                return { provider, status: "missing", detail: msg };
+            }
+            if (lower.includes("econnrefused") ||
+                lower.includes("enotfound") ||
+                lower.includes("could not resolve") ||
+                lower.includes("timeout") ||
+                lower.includes("network") ||
+                lower.includes("cannot connect")) {
+                return { provider, status: "network", detail: msg };
+            }
+            return { provider, status: "unknown", detail: msg };
+        }
+    }
     // ========================================
     // ENHANCED: Tool Event Emission API
     // ========================================