@juspay/neurolink 11.0.0 → 11.1.1

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

@@ -47,6 +47,41 @@ export declare class RateLimitError extends ProviderError {
 export declare class InvalidModelError extends ProviderError {
     constructor(message: string, provider?: string);
 }
+/**
+ * Everything a ProviderErrorRule's `match`/`message` functions can inspect
+ * about a raw thrown error, pre-extracted once so every rule doesn't
+ * re-derive the same duck-typed fields.
+ */
+export type ProviderErrorContext = {
+    /** The raw thrown value, for rules that need custom inspection beyond the extracted fields. */
+    error: unknown;
+    /** `.message` off the raw error, or "Unknown error" if absent/non-string. */
+    message: string;
+    /** HTTP status code, duck-typed from `.statusCode` / `.status`. */
+    statusCode: number | undefined;
+    /** `.name` off the raw error (e.g. AWS SDK exception names like "ThrottlingException"). */
+    errorName: string | undefined;
+    /** `.code` off the raw error (e.g. AWS SDK / Node network error codes). */
+    errorCode: string | undefined;
+    /** Provider key passed to classifyProviderError (e.g. "mistral", "vertex"). */
+    provider: string;
+    /** Model name in effect for this call, when the caller has one available. */
+    modelName: string | undefined;
+};
+/**
+ * One row of a provider's error-classification table. Rules are tried in
+ * array order; the first `match` to return true wins. `errorClass` must be
+ * `ProviderError` or one of its subclasses (AuthenticationError,
+ * RateLimitError, InvalidModelError, NetworkError, ...) sharing its
+ * `(message, provider?)` constructor shape. `message` can be a static
+ * string or a function of the context, for providers that need to
+ * interpolate a model name, a scraped retry-delay, or an AWS error code.
+ */
+export type ProviderErrorRule = {
+    match: (ctx: ProviderErrorContext) => boolean;
+    errorClass: new (message: string, provider?: string) => ProviderError;
+    message: string | ((ctx: ProviderErrorContext) => string);
+};
 /**
  * Base class for OAuth-specific errors
  */

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

@@ -96,6 +96,7 @@ export type NeurolinkCredentials = {
     };
     googleAiStudio?: {
         apiKey?: string;
+        baseURL?: string;
     };
     vertex?: {
         projectId?: string;
@@ -888,6 +889,8 @@ export type GenAIClient = {
 export type GoogleGenAIHttpOptions = {
     /** Custom fetch implementation for proxy support */
     fetch?: typeof fetch;
+    /** Override the API base URL (e.g. a corporate proxy or mock endpoint) */
+    baseUrl?: string;
 };
 /**
  * Google GenAI constructor type
@@ -1677,6 +1680,82 @@ export type ProviderRegistration = {
     constructor: ProviderConstructor;
     defaultModel?: string;
     aliases?: string[];
+    descriptor?: ProviderDescriptor;
+};
+/**
+ * Single source of truth for one AI provider's static identity: how it's
+ * addressed (name/aliases), how it's authenticated (credentialsKey/envVars),
+ * what it defaults to (defaultModel), and how the rest of the codebase
+ * should treat it (toolSupport/localRuntime/healthCheck). Every consumer
+ * that used to hand-maintain its own provider table (CLI choices,
+ * CREDENTIAL_KEY_MAP, env-var checks, health-check dispatch, auto-select
+ * priority, PROMPT_ONLY_TOOL_PROVIDERS) derives from PROVIDER_DESCRIPTORS
+ * instead. See src/lib/factories/providerDescriptors.ts for the data.
+ */
+export type ProviderDescriptor = {
+    /** Canonical identity — matches an AIProviderName enum member (never AUTO). */
+    name: AIProviderName;
+    /** Alternate spellings accepted by the CLI and the alias index (kebab-case, shorthand, legacy names). Does not include `name` itself. */
+    aliases: readonly string[];
+    /** Key into NeurolinkCredentials for per-call/per-instance credential overrides. */
+    credentialsKey: keyof NeurolinkCredentials;
+    /** Environment variables this provider reads at runtime. */
+    envVars: {
+        /** Primary identity/secret env var. Absent for providers with no required credential (Ollama, LM Studio, llama.cpp) or that use extraRequired instead of a single key (Vertex). */
+        apiKey?: string;
+        /** Alternate env vars accepted in place of apiKey, checked in order after apiKey. */
+        fallbacks?: readonly string[];
+        baseURL?: string;
+        /** Alternate env vars accepted in place of baseURL. */
+        baseURLFallbacks?: readonly string[];
+        /** Env var that overrides the static defaultModel at runtime. */
+        model?: string;
+        /** Alternate env vars accepted in place of model, checked in order after model. */
+        modelFallbacks?: readonly string[];
+        /** Additional env vars required alongside apiKey (e.g. AWS secret key, Azure endpoint). */
+        extraRequired?: readonly string[];
+        /** Alternate ways to satisfy extraRequired when it isn't a plain env-var list (e.g. Vertex's file-path-OR-individual-fields auth). Each entry is either a single env var name (satisfied alone) or a nested array of names that must ALL be present together (e.g. Vertex's GOOGLE_AUTH_CLIENT_EMAIL + GOOGLE_AUTH_PRIVATE_KEY pair, which is only valid as a pair). Evaluate with `satisfiesFallbacks()` (providerConfig.ts) rather than re-deriving this logic at each call site. */
+        extraRequiredFallbacks?: readonly (string | readonly string[])[];
+        /** True when the provider is usable with zero configuration (local runtime with a documented default URL, or a documented non-secret default like LiteLLM's "sk-anything"). */
+        optional?: boolean;
+    };
+    /**
+     * Static fallback model. The empty string "" is a documented sentinel
+     * meaning "no static default — resolved at runtime via envVars.model or
+     * provider-side auto-discovery" (used by Bedrock, OpenAI-Compatible,
+     * LM Studio, llama.cpp, matching how providerRegistry.ts already passes
+     * `undefined` as their defaultModel argument today).
+     */
+    defaultModel: string;
+    toolSupport: "native" | "prompt-only" | "none" | "model-dependent";
+    /** True only for providers that run entirely on the caller's machine with no cloud account (Ollama, LM Studio, llama.cpp). LiteLLM is a local proxy but commonly points at cloud models, so it is deliberately false. */
+    localRuntime: boolean;
+    /** How ProviderHealthChecker should verify this provider is reachable. */
+    healthCheck: "env-only" | "models-probe" | "live-generate";
+    setupUrl?: string;
+    timeouts?: {
+        generateMs?: number;
+        streamMs?: number;
+    };
+    /** Ascending priority (1 = tried first) in the auto-select fallback chain used by getBestProvider(). Undefined = not part of the auto-select chain. */
+    autoSelectPriority?: number;
+    /** Format-validation regex sourced from providerConfig.ts's API_KEY_FORMATS, when one exists for this provider. */
+    apiKeyFormatPattern?: RegExp;
+    /**
+     * True when this provider's credentials are resolved by an external chain
+     * or its own config validator rather than by plain env-var presence, so
+     * its required-env-vars can't be expressed as "every one of these exact
+     * names must be literally set". Examples: Vertex accepts a service-account
+     * file OR individual client-email/private-key fields OR a base64 key
+     * (an OR, not an AND, of auth paths); Bedrock falls back to the AWS SDK's
+     * own default credential chain (shared profile, IAM role) with no env
+     * vars required at all; LiteLLM is a documented zero-config local proxy.
+     * `ProviderHealthChecker.getRequiredEnvironmentVariables()` returns `[]`
+     * for these providers and defers to `checkProviderSpecificConfig()`'s
+     * dedicated per-provider check instead of deriving a flat AND-list from
+     * `envVars`.
+     */
+    credentialsResolvedExternally?: boolean;
 };
 /** Minimal NeuroLink-like instance accepted by the image generation service. */
 export type NeuroLinkInstance = {

package/dist/lib/utils/errorClassifier.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared provider-error classification. Every provider's
+ * `formatProviderError(error)` delegates here instead of hand-rolling its
+ * own TimeoutError-check → .includes()-chain → `new XError(...)` ladder.
+ *
+ * `classifyProviderError` picks the Error subclass + message; it does NOT
+ * stamp statusCode/isRetryable/retryAfterMs onto the result — that
+ * passthrough already happens generically in
+ * `BaseProvider.handleProviderError()` (src/lib/core/baseProvider.ts) for
+ * every provider's returned error, migrated or not, so duplicating it here
+ * would risk the two copies disagreeing.
+ */
+import { type ProviderErrorRule } from "../types/index.js";
+/**
+ * Classify a raw provider error into a NeuroLink `ProviderError` subclass.
+ * `rules` are tried in order; the first match wins. `TimeoutError` is
+ * always handled first, ahead of any rule table — every provider treated
+ * it identically before this change, so it is not made overridable.
+ */
+export declare function classifyProviderError(error: unknown, rules: ProviderErrorRule[], provider: string, modelName?: string): Error;
+/**
+ * Generic fallback rule table covering the five categories every
+ * OpenAI-compatible provider already hand-rolled near-identically:
+ * auth (401), rate limit (429), model-not-found (404), network/connection
+ * errors, and 5xx server errors. Providers with a provider-specific auth
+ * message (naming the exact env var) prepend one override rule and spread
+ * this table after it — see errorClassifier usage in any migrated
+ * provider's formatProviderError for the pattern.
+ */
+export declare const DEFAULT_ERROR_RULES: ProviderErrorRule[];

package/dist/lib/utils/errorClassifier.js

@@ -0,0 +1,183 @@
+/**
+ * Shared provider-error classification. Every provider's
+ * `formatProviderError(error)` delegates here instead of hand-rolling its
+ * own TimeoutError-check → .includes()-chain → `new XError(...)` ladder.
+ *
+ * `classifyProviderError` picks the Error subclass + message; it does NOT
+ * stamp statusCode/isRetryable/retryAfterMs onto the result — that
+ * passthrough already happens generically in
+ * `BaseProvider.handleProviderError()` (src/lib/core/baseProvider.ts) for
+ * every provider's returned error, migrated or not, so duplicating it here
+ * would risk the two copies disagreeing.
+ */
+import { ProviderError, AuthenticationError, RateLimitError, InvalidModelError, NetworkError, } from "../types/index.js";
+import { TimeoutError } from "./timeout.js";
+import { duckTypedStatusCode } from "./providerRetry.js";
+import { TRANSIENT_NETWORK_CODES } from "../constants/networkErrorCodes.js";
+import { redactUrlsInText } from "./logSanitize.js";
+/** Bounded walk depth for `.cause` chains — matches the precedent in
+ * `proxy/proxyFetch.ts`'s `isTransientNetworkError`. Guards against
+ * pathological/cyclic `.cause` chains hanging classification. */
+const MAX_CAUSE_DEPTH = 5;
+/**
+ * Walk `error.cause` up to `MAX_CAUSE_DEPTH` links, guarded by a seen-set so
+ * a cyclic chain (`a.cause === a`, or a longer cycle) terminates instead of
+ * looping. Node's native `fetch` (undici) throws `TypeError: fetch failed`
+ * with the real transport error nested under `.cause` — sometimes another
+ * level deep (e.g. a SocketError inside a ConnectTimeoutError) — so a
+ * classifier that only reads the outer error's `.message`/`.code` never
+ * sees it.
+ */
+function collectCauseChain(error) {
+    const chain = [];
+    const seen = new Set();
+    let current = error;
+    while (current &&
+        typeof current === "object" &&
+        !seen.has(current) &&
+        chain.length < MAX_CAUSE_DEPTH) {
+        seen.add(current);
+        const record = current;
+        chain.push(record);
+        current = record.cause;
+    }
+    return chain;
+}
+function firstString(chain, key) {
+    for (const record of chain) {
+        if (typeof record[key] === "string") {
+            return record[key];
+        }
+    }
+    return undefined;
+}
+function buildErrorContext(error, provider, modelName) {
+    const chain = collectCauseChain(error);
+    const top = chain[0];
+    const topMessage = typeof top?.message === "string"
+        ? top.message
+        : error instanceof Error
+            ? error.message
+            : "Unknown error";
+    // Compose (never replace) the message: append the deepest cause's message
+    // when it differs from the top, so existing rules matching the outer text
+    // (e.g. "rate limit", "model not found") keep matching, while the real
+    // transport failure buried in .cause becomes visible to rules that need
+    // it (e.g. a nested "ECONNREFUSED").
+    // The nested message is redacted before it is composed in: an undici cause
+    // carries the full request URL, so a presigned token would otherwise reach
+    // a client-facing error message through this path. Only the nested text is
+    // scrubbed — the provider's own top-level message is left alone, since
+    // several providers deliberately name their base URL in it.
+    const deepest = chain[chain.length - 1];
+    const deepestMessage = typeof deepest?.message === "string"
+        ? redactUrlsInText(deepest.message)
+        : undefined;
+    const message = deepestMessage && deepestMessage !== topMessage
+        ? `${topMessage}: ${deepestMessage}`
+        : topMessage;
+    // errorCode/errorName/statusCode: prefer the outer error's own value,
+    // falling back to the first cause in the chain that has one.
+    let statusCode;
+    for (const record of chain) {
+        statusCode = duckTypedStatusCode(record);
+        if (statusCode !== undefined) {
+            break;
+        }
+    }
+    return {
+        error,
+        message,
+        statusCode,
+        errorName: firstString(chain, "name"),
+        errorCode: firstString(chain, "code"),
+        provider,
+        modelName,
+    };
+}
+/**
+ * Classify a raw provider error into a NeuroLink `ProviderError` subclass.
+ * `rules` are tried in order; the first match wins. `TimeoutError` is
+ * always handled first, ahead of any rule table — every provider treated
+ * it identically before this change, so it is not made overridable.
+ */
+export function classifyProviderError(error, rules, provider, modelName) {
+    if (error instanceof TimeoutError) {
+        return new NetworkError(`Request timed out: ${error.message}`, provider);
+    }
+    const ctx = buildErrorContext(error, provider, modelName);
+    const rule = rules.find((r) => r.match(ctx));
+    if (!rule) {
+        return new ProviderError(`${provider} error: ${ctx.message}`, provider);
+    }
+    const message = typeof rule.message === "function" ? rule.message(ctx) : rule.message;
+    return new rule.errorClass(message, provider);
+}
+/**
+ * Generic fallback rule table covering the five categories every
+ * OpenAI-compatible provider already hand-rolled near-identically:
+ * auth (401), rate limit (429), model-not-found (404), network/connection
+ * errors, and 5xx server errors. Providers with a provider-specific auth
+ * message (naming the exact env var) prepend one override rule and spread
+ * this table after it — see errorClassifier usage in any migrated
+ * provider's formatProviderError for the pattern.
+ */
+export const DEFAULT_ERROR_RULES = [
+    {
+        match: (ctx) => ctx.statusCode === 401 ||
+            /API_KEY_INVALID|Invalid API key|Unauthorized|invalid_api_key/i.test(ctx.message),
+        errorClass: AuthenticationError,
+        message: (ctx) => `Invalid ${ctx.provider} API key. Please check your credentials.`,
+    },
+    {
+        match: (ctx) => ctx.statusCode === 429 || /rate limit/i.test(ctx.message),
+        errorClass: RateLimitError,
+        message: (ctx) => `${ctx.provider} rate limit exceeded. Please try again later.`,
+    },
+    {
+        match: (ctx) => ctx.statusCode === 404 ||
+            /model_not_found|model not found/i.test(ctx.message),
+        errorClass: InvalidModelError,
+        message: (ctx) => ctx.modelName
+            ? `${ctx.provider} model '${ctx.modelName}' not found.`
+            : `${ctx.provider} model not found.`,
+    },
+    {
+        // Message regex covers providers/SDKs that surface a code as text
+        // (e.g. AWS SDK wrapping "ECONNRESET" into its own message). errorCode
+        // covers undici's native fetch(), which wraps transport failures as
+        // `TypeError: fetch failed` and puts the *structured* code
+        // (ECONNREFUSED, UND_ERR_SOCKET, ...) on a nested `.cause` rather than
+        // in any message text — buildErrorContext's cause walk surfaces it here.
+        match: (ctx) => /ECONNRESET|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|network|connection/i.test(ctx.message) ||
+            (ctx.errorCode !== undefined &&
+                TRANSIENT_NETWORK_CODES.has(ctx.errorCode)),
+        errorClass: NetworkError,
+        message: (ctx) => `Connection error: ${ctx.message}`,
+    },
+    {
+        // Batch J Task 3: the old `/\b5\d\d\b/` matched ANY bare 3-digit number
+        // in [500,599) anywhere in the message — e.g. "max_tokens (500) exceeds
+        // model limit" — with no relation to an actual HTTP status. Tightened to
+        // require the number sit in a status-shaped context: immediately next
+        // to "error" (either order) or "status"/"status code" (a common HTTP
+        // client wrapper phrase, e.g. axios's "Request failed with status code
+        // 500"), with a bounded gap so unrelated digits nearby can't bridge the
+        // match — or a named 5xx phrase that needs no digit at all ("bad
+        // gateway", "service unavailable", "gateway timeout", "server error",
+        // which already covers "... Internal Server Error"). This changes the
+        // MATCHED MESSAGE TEXT only, never the classified class: when no rule
+        // matches, `classifyProviderError`'s fallback also returns
+        // `ProviderError` (see above) — the same class this rule assigns — so
+        // narrowing this regex can only move a message between "${provider}
+        // server error: ..." and "${provider} error: ...", never between error
+        // classes.
+        match: (ctx) => (ctx.statusCode !== undefined &&
+            ctx.statusCode >= 500 &&
+            ctx.statusCode <= 599) ||
+            /server error|bad gateway|service unavailable|gateway timeout|\berror\b\D{0,12}\b5\d\d\b|\b5\d\d\b\D{0,12}\berror\b|\bstatus(?:\s*code)?\b\D{0,12}\b5\d\d\b/i.test(ctx.message),
+        errorClass: ProviderError,
+        message: (ctx) => `${ctx.provider} server error: ${ctx.message}`,
+    },
+];
+//# sourceMappingURL=errorClassifier.js.map

package/dist/lib/utils/fileDetector.js

@@ -26,6 +26,7 @@ import { fileTypeForExtension, lookupByMimeType, normalizeExtension, } from "../
 import { LANGUAGE_MAP } from "../processors/config/languageMap.js";
 import { getMimeTypeForExtension, TEXT_EXTENSION_MIME_MAP, } from "../processors/config/mimeConstants.js";
 import { CSVProcessor } from "./csvProcessor.js";
+import { withRetry } from "../core/infrastructure/retry.js";
 import { ImageProcessor } from "./imageProcessor.js";
 import { detectIsoBmffImageMimeType, hasFtypBoxSignature } from "./isoBmff.js";
 import { logger } from "./logger.js";
@@ -34,11 +35,6 @@ import { withTimeout } from "./errorHandling.js";
 import { normalizeUrlForCache, redactUrlForError, sanitizeErrorCause, } from "./logSanitize.js";
 import { mimeHintToExtension, mimeHintToFileType, normalizeMimeHint, } from "./mimeTypeHints.js";
 import { PDFProcessor } from "./pdfProcessor.js";
-/**
- * Default retry configuration constants
- */
-const DEFAULT_MAX_RETRIES = 3;
-const DEFAULT_RETRY_DELAY = 1000; // milliseconds
 /**
  * Short-TTL cache of URL → Content-Type (#323). A URL is commonly detected more
  * than once (repeated multimodal prompts reuse the same asset URL); caching the
@@ -202,41 +198,6 @@ function isRetryableNetworkError(error) {
     ];
     return transientKeywords.some((keyword) => errorMessage.includes(keyword));
 }
-/**
- * Execute an operation with automatic retry logic on transient network errors
- *
- * @param operation - Async function to execute
- * @param options - Retry configuration options
- * @returns Promise resolving to the operation result
- * @throws Error if all retry attempts fail or error is non-retryable
- */
-async function withRetry(operation, options = {}) {
-    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
-    const retryDelay = options.retryDelay ?? DEFAULT_RETRY_DELAY;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-            return await operation();
-        }
-        catch (error) {
-            const isRetryable = isRetryableNetworkError(error);
-            const isLastAttempt = attempt === maxRetries;
-            if (!isRetryable || isLastAttempt) {
-                throw error;
-            }
-            // Calculate exponential backoff delay
-            const delay = retryDelay * 2 ** attempt;
-            logger.debug("Retrying network operation after transient error", {
-                attempt: attempt + 1,
-                maxRetries,
-                delay,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            await new Promise((resolve) => setTimeout(resolve, delay));
-        }
-    }
-    // TypeScript exhaustiveness check - should never reach here
-    throw new Error("Retry logic failed unexpectedly");
-}
 /**
  * Check if text has JSON markers (starts with { or [ and ends with corresponding closing bracket)
  */
@@ -1542,8 +1503,6 @@ export class FileDetector {
     static async loadFromURL(url, options) {
         const maxSize = options?.maxSize || 200 * 1024 * 1024; // 200MB default (matches Curator memory-safety cap)
         const timeout = options?.timeout || FileDetector.DEFAULT_NETWORK_TIMEOUT;
-        const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
-        const retryDelay = options?.retryDelay ?? DEFAULT_RETRY_DELAY;
         // #317: pre-flight HEAD to reject an oversized file BEFORE downloading any
         // body. content-length is advisory (chunked responses omit it), so a
         // missing/invalid header — or a server that refuses HEAD — falls through to
@@ -1641,7 +1600,11 @@ export class FileDetector {
                 }
                 throw redacted;
             }
-        }, { maxRetries, retryDelay });
+        }, {
+            maxRetries: options?.maxRetries ?? 3,
+            baseDelayMs: options?.retryDelay ?? 1000,
+            shouldRetry: isRetryableNetworkError,
+        });
     }
     /**
      * Load file from filesystem path

package/dist/lib/utils/providerConfig.d.ts

@@ -70,6 +70,22 @@ export declare function getProviderModel(envVar: string, defaultModel: string):
  * @returns True if one of the credentials is available
  */
 export declare function hasProviderCredentials(envVars: string[]): boolean;
+/**
+ * Evaluates a `ProviderDescriptor.envVars.extraRequiredFallbacks`-shaped
+ * list against an env-var source. Each entry is either a single env var
+ * name (satisfied on its own) or a nested array of names that must ALL be
+ * present together (e.g. Vertex's GOOGLE_AUTH_CLIENT_EMAIL +
+ * GOOGLE_AUTH_PRIVATE_KEY pair, which is only valid auth as a pair).
+ * Returns true when at least one entry is satisfied. The single evaluation
+ * site for this shape — every consumer (providerUtils.ts, providerHealth.ts,
+ * setup.ts, environmentManager.ts) must call this instead of re-deriving the
+ * same `.some()`/`.every()` logic, so they can't drift out of sync with each
+ * other or with the real auth gate (hasGoogleCredentials()).
+ * @param env Explicit env-var source (`process.env`, or a parsed .env file) —
+ *   never hardcoded, so callers checking a file's contents (not the live
+ *   process env) can reuse this too.
+ */
+export declare function satisfiesFallbacks(fallbacks: readonly (string | readonly string[])[] | undefined, env: Record<string, string | undefined>): boolean;
 /**
  * Creates Anthropic provider configuration
  * Supports both API key and OAuth authentication methods

package/dist/lib/utils/providerConfig.js

@@ -185,6 +185,29 @@ export function getProviderModel(envVar, defaultModel) {
 export function hasProviderCredentials(envVars) {
     return envVars.some((envVar) => !!process.env[envVar]);
 }
+/**
+ * Evaluates a `ProviderDescriptor.envVars.extraRequiredFallbacks`-shaped
+ * list against an env-var source. Each entry is either a single env var
+ * name (satisfied on its own) or a nested array of names that must ALL be
+ * present together (e.g. Vertex's GOOGLE_AUTH_CLIENT_EMAIL +
+ * GOOGLE_AUTH_PRIVATE_KEY pair, which is only valid auth as a pair).
+ * Returns true when at least one entry is satisfied. The single evaluation
+ * site for this shape — every consumer (providerUtils.ts, providerHealth.ts,
+ * setup.ts, environmentManager.ts) must call this instead of re-deriving the
+ * same `.some()`/`.every()` logic, so they can't drift out of sync with each
+ * other or with the real auth gate (hasGoogleCredentials()).
+ * @param env Explicit env-var source (`process.env`, or a parsed .env file) —
+ *   never hardcoded, so callers checking a file's contents (not the live
+ *   process env) can reuse this too.
+ */
+export function satisfiesFallbacks(fallbacks, env) {
+    if (!fallbacks) {
+        return false;
+    }
+    return fallbacks.some((entry) => typeof entry === "string"
+        ? !!env[entry]
+        : entry.every((name) => !!env[name]));
+}
 // =============================================================================
 // PROVIDER-SPECIFIC CONFIGURATION CREATORS
 // =============================================================================

package/dist/lib/utils/providerHealth.d.ts

@@ -36,21 +36,54 @@ export declare class ProviderHealthChecker {
      */
     private static checkModelAvailability;
     /**
-     * Get required environment variables for a provider
-     */
-    private static getRequiredEnvironmentVariables;
-    /**
-     * Get API key environment variable for a provider
-     */
-    private static getApiKeyEnvironmentVariable;
+     * Get required environment variables for a provider.
+     *
+     * Returns `[]` for providers with `descriptor.credentialsResolvedExternally
+     * === true` (Vertex, Bedrock, LiteLLM) — the check in
+     * checkEnvironmentConfiguration() below ANDs every entry in the returned
+     * list together, which can't express Vertex's file-OR-individual-creds-
+     * OR-service-account auth, Bedrock's AWS SDK default provider chain
+     * (profile / IAM role, no env vars at all), or LiteLLM's documented
+     * zero-config local proxy. Their real requirement is validated by
+     * checkProviderSpecificConfig()'s dedicated per-provider checks instead.
+     * Naively deriving [apiKey, ...extraRequired] from the descriptor for
+     * these three (as for the other 27 providers) would make
+     * checkEnvironmentConfiguration() push a false "missing environment
+     * variables" issue — and therefore isHealthy=false — for legitimate
+     * fallback-based Vertex auth, AWS_PROFILE/IAM-role Bedrock auth, and
+     * unauthenticated local LiteLLM proxies. See hasProviderEnvVars() in
+     * providerUtils.ts for the equivalent OR-aware check used for
+     * auto-select gating. See `ProviderDescriptor.credentialsResolvedExternally`
+     * (types/providers.ts) for the field's full documentation.
+     */
+    static getRequiredEnvironmentVariables(providerName: string): string[];
+    /**
+     * Get API key environment variable for a provider.
+     *
+     * Dead code at its sole call site today (checkApiKeyValidity() early-
+     * returns for VERTEX/OLLAMA/BEDROCK/LITELLM before reaching this), but
+     * now `static` (public) so a future direct caller is plausible — hence
+     * the two intentional diffs from the original hand-written switch are
+     * documented here rather than left silent:
+     *   - vertex: old switch returned "GOOGLE_APPLICATION_CREDENTIALS"
+     *     (one of several valid auth vars); the descriptor's `envVars.apiKey`
+     *     is "GOOGLE_CLOUD_PROJECT_ID" instead — the actual identity var for
+     *     the provider, not one specific credential-supply mechanism.
+     *   - ollama: old switch returned "OLLAMA_BASE_URL"; the descriptor has
+     *     no `envVars.apiKey` for ollama (it's a local, unauthenticated
+     *     runtime), so this now returns "".
+     * Both are kept deliberately (semantically truer identity vars) rather
+     * than reproduced byte-for-byte from the old switch.
+     */
+    static getApiKeyEnvironmentVariable(providerName: string): string;
     /**
      * Validate API key format for a provider
      */
-    private static validateApiKeyFormat;
+    static validateApiKeyFormat(providerName: string, apiKey: string): boolean;
     /**
      * Get health check endpoint for connectivity testing
      */
-    private static getProviderHealthEndpoint;
+    static getProviderHealthEndpoint(providerName: string): string | null;
     /**
      * Provider-specific configuration checks
      */
@@ -72,9 +105,17 @@ export declare class ProviderHealthChecker {
      */
     private static checkGoogleApplicationCredentials;
     /**
-     * Check individual Google credentials
-     */
-    private static checkIndividualGoogleCredentials;
+     * Check Vertex's non-file auth fallbacks (GOOGLE_APPLICATION_CREDENTIALS_
+     * NEUROLINK, GOOGLE_SERVICE_ACCOUNT_KEY, or the GOOGLE_AUTH_CLIENT_EMAIL +
+     * GOOGLE_AUTH_PRIVATE_KEY pair) via the descriptor's extraRequiredFallbacks
+     * instead of a hand-maintained env-var list, so this stays in sync with
+     * the real gating logic (hasGoogleCredentials()) the same way
+     * checkApiKeyValidity()'s vertex branch does. The previous hand-rolled
+     * version only recognized GOOGLE_SERVICE_ACCOUNT_KEY or the email+key
+     * pair — missing GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK, the
+     * descriptor's documented first-priority fallback.
+     */
+    private static checkExtraRequiredFallbackCredentials;
     /**
      * Check AWS Bedrock configuration
      */