@juspay/neurolink 11.0.0 → 11.1.0

package/dist/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,67 @@ 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). */
+        extraRequiredFallbacks?: 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;
 };
 /** Minimal NeuroLink-like instance accepted by the image generation service. */
 export type NeuroLinkInstance = {

package/dist/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/utils/errorClassifier.js

@@ -0,0 +1,93 @@
+/**
+ * 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";
+function buildErrorContext(error, provider, modelName) {
+    const record = error && typeof error === "object"
+        ? error
+        : undefined;
+    const message = typeof record?.message === "string"
+        ? record.message
+        : error instanceof Error
+            ? error.message
+            : "Unknown error";
+    return {
+        error,
+        message,
+        statusCode: duckTypedStatusCode(error),
+        errorName: typeof record?.name === "string" ? record.name : undefined,
+        errorCode: typeof record?.code === "string" ? record.code : undefined,
+        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.`,
+    },
+    {
+        match: (ctx) => /ECONNRESET|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|network|connection/i.test(ctx.message),
+        errorClass: NetworkError,
+        message: (ctx) => `Connection error: ${ctx.message}`,
+    },
+    {
+        match: (ctx) => (ctx.statusCode !== undefined && ctx.statusCode >= 500) ||
+            /\b5\d\d\b|server error/i.test(ctx.message),
+        errorClass: ProviderError,
+        message: (ctx) => `${ctx.provider} server error: ${ctx.message}`,
+    },
+];

package/dist/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/utils/providerHealth.d.ts

@@ -36,21 +36,56 @@ export declare class ProviderHealthChecker {
      */
     private static checkModelAvailability;
     /**
-     * Get required environment variables for a provider
-     */
-    private static getRequiredEnvironmentVariables;
+     * Providers whose credential model can't be reduced to "every one of
+     * these exact env vars must be literally set" — 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 — matches the original hand-written switch's
+     * deliberate `return []` for exactly these three. Naively deriving
+     * [apiKey, ...extraRequired] from the descriptor here (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.
+     */
+    private static readonly ENV_CHECK_DELEGATED_TO_SPECIFIC_CONFIG;
     /**
-     * Get API key environment variable for a provider
+     * Get required environment variables for a provider
      */
-    private static getApiKeyEnvironmentVariable;
+    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
      */

package/dist/utils/providerHealth.js

@@ -4,10 +4,11 @@
  */
 import { logger } from "./logger.js";
 import { AIProviderName, OpenAIModels, GoogleAIModels, AnthropicModels, BedrockModels, } from "../constants/enums.js";
-import { API_KEY_LENGTHS, PROJECT_ID_FORMAT } from "./providerConfig.js";
+import { PROJECT_ID_FORMAT } from "./providerConfig.js";
 import { basename } from "path";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { DEFAULT_OLLAMA_MODEL } from "../providers/ollama/constants.js";
+import { ProviderFactory } from "../factories/providerFactory.js";
 export class ProviderHealthChecker {
     static healthCache = new Map();
     static DEFAULT_TIMEOUT = 5000; // 5 seconds
@@ -172,55 +173,36 @@ export class ProviderHealthChecker {
             logger.debug("Vertex AI authentication check starting", {
                 providerName,
             });
-            // Method 1: Check GOOGLE_APPLICATION_CREDENTIALS (file-based)
-            const credentialsFile = process.env.GOOGLE_APPLICATION_CREDENTIALS;
-            let fileBasedAuthValid = false;
-            if (credentialsFile) {
-                logger.debug("Checking GOOGLE_APPLICATION_CREDENTIALS file");
-                try {
-                    const { promises: fs } = await import("fs");
-                    try {
-                        await fs.access(credentialsFile);
-                        fileBasedAuthValid = true;
-                    }
-                    catch {
-                        fileBasedAuthValid = false;
-                    }
-                    logger.debug("File auth check result", {
-                        fileExists: fileBasedAuthValid,
-                    });
-                }
-                catch (error) {
-                    logger.debug("File auth check error", {
-                        error: String(error),
-                    });
-                    fileBasedAuthValid = false;
-                }
-            }
-            // Method 2: Check individual environment variables
-            const hasIndividualAuth = !!(process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
-                process.env.GOOGLE_AUTH_PRIVATE_KEY);
-            logger.debug("Individual auth check", {
-                hasClientEmail: !!process.env.GOOGLE_AUTH_CLIENT_EMAIL,
-                hasPrivateKey: !!process.env.GOOGLE_AUTH_PRIVATE_KEY,
-                hasIndividualAuth,
-            });
-            // Vertex is valid if EITHER auth method works
-            const hasValidAuth = fileBasedAuthValid || hasIndividualAuth;
-            logger.debug("Vertex auth final result", {
-                fileBasedAuthValid,
-                hasIndividualAuth,
-                hasValidAuth,
-            });
+            // Derive auth-var acceptance from the vertex descriptor instead of a
+            // hand-maintained var list, so this stays in sync with the real
+            // gating logic (hasGoogleCredentials() in googleVertex/client.ts and
+            // googleVertex/utils.ts): extraRequired.every(...) ||
+            // extraRequiredFallbacks.some(...), the same pattern used by
+            // hasProviderEnvVars() (providerUtils.ts), setup.ts, and
+            // environmentManager.ts. The old two-method check here only
+            // recognized GOOGLE_APPLICATION_CREDENTIALS or the
+            // GOOGLE_AUTH_CLIENT_EMAIL + GOOGLE_AUTH_PRIVATE_KEY pair — missing
+            // GOOGLE_SERVICE_ACCOUNT_KEY and, most importantly,
+            // GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK, the descriptor's
+            // documented first-priority fallback. A user configured via that
+            // var alone had a fully working Vertex provider but was reported
+            // unhealthy here. Note: this is a presence-only check — it no
+            // longer verifies the GOOGLE_APPLICATION_CREDENTIALS file actually
+            // exists on disk (the old file-based method did via fs.access),
+            // matching the presence-only semantics already used by the other
+            // three callers of this pattern.
+            const descriptor = ProviderFactory.getDescriptor(AIProviderName.VERTEX);
+            const { extraRequired, extraRequiredFallbacks } = descriptor?.envVars ?? {};
+            const hasValidAuth = (extraRequired ?? []).every((v) => !!process.env[v]) ||
+                (extraRequiredFallbacks ?? []).some((v) => !!process.env[v]);
+            logger.debug("Vertex auth final result", { hasValidAuth });
             if (hasValidAuth) {
                 healthStatus.hasApiKey = true;
-                logger.debug("Vertex auth SUCCESS", {
-                    authMethod: fileBasedAuthValid ? "file-based" : "individual-env-vars",
-                });
+                logger.debug("Vertex auth SUCCESS");
             }
             else {
                 healthStatus.hasApiKey = false;
-                healthStatus.configurationIssues.push(`Vertex AI authentication not found: neither GOOGLE_APPLICATION_CREDENTIALS file nor individual credentials (GOOGLE_AUTH_CLIENT_EMAIL + GOOGLE_AUTH_PRIVATE_KEY) are properly configured`);
+                healthStatus.configurationIssues.push("Vertex AI authentication not found: set GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK, GOOGLE_SERVICE_ACCOUNT_KEY, or both GOOGLE_AUTH_CLIENT_EMAIL and GOOGLE_AUTH_PRIVATE_KEY");
                 logger.debug("Vertex auth FAILED", {
                     reason: "No valid auth method found",
                 });
@@ -359,104 +341,115 @@ export class ProviderHealthChecker {
             }
         }
     }
+    /**
+     * Providers whose credential model can't be reduced to "every one of
+     * these exact env vars must be literally set" — 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 — matches the original hand-written switch's
+     * deliberate `return []` for exactly these three. Naively deriving
+     * [apiKey, ...extraRequired] from the descriptor here (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.
+     */
+    static ENV_CHECK_DELEGATED_TO_SPECIFIC_CONFIG = new Set([
+        AIProviderName.VERTEX,
+        AIProviderName.BEDROCK,
+        AIProviderName.LITELLM,
+    ]);
     /**
      * Get required environment variables for a provider
      */
     static getRequiredEnvironmentVariables(providerName) {
-        switch (providerName) {
-            case AIProviderName.ANTHROPIC:
-                return ["ANTHROPIC_API_KEY"];
-            case AIProviderName.OPENAI:
-                return ["OPENAI_API_KEY"];
-            case AIProviderName.VERTEX:
-                // Vertex AI requires authentication, but not via a single environment variable.
-                // Authentication can be provided via a credential file or individual credentials + project.
-                // The required authentication is checked in checkProviderSpecificConfig instead of here.
-                // Returning an empty array here does NOT mean authentication is not required.
-                return [];
-            case AIProviderName.GOOGLE_AI:
-                return ["GOOGLE_AI_API_KEY"];
-            case AIProviderName.BEDROCK:
-                // Bedrock credentials are resolved via AWS SDK default provider chain.
-                // Region/auth validated in provider-specific checks.
-                return [];
-            case AIProviderName.AZURE:
-                return ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"];
-            case AIProviderName.LITELLM:
-                return [];
-            case AIProviderName.OLLAMA:
-                return []; // Ollama typically doesn't require API keys
-            default:
-                return [];
-        }
+        // Resolve the descriptor FIRST so the delegation-Set check below is
+        // keyed on the canonical, alias-resolved `descriptor.name` — not the
+        // raw, possibly-aliased `providerName` argument. Checking the raw
+        // input here would let documented aliases (e.g. "googleVertex" for
+        // vertex, "aws" for bedrock) skip the delegation and fall through to
+        // the naive [apiKey, ...extraRequired] derivation below, reproducing
+        // the exact false "missing environment variables" regression this
+        // Set exists to prevent.
+        const descriptor = ProviderFactory.getDescriptor(providerName);
+        if (!descriptor) {
+            return [];
+        }
+        if (this.ENV_CHECK_DELEGATED_TO_SPECIFIC_CONFIG.has(descriptor.name)) {
+            return [];
+        }
+        const { apiKey, extraRequired } = descriptor.envVars;
+        return [...(apiKey ? [apiKey] : []), ...(extraRequired ?? [])];
     }
     /**
-     * Get API key environment variable for a provider
+     * 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) {
-        switch (providerName) {
-            case AIProviderName.ANTHROPIC:
-                return "ANTHROPIC_API_KEY";
-            case AIProviderName.OPENAI:
-                return "OPENAI_API_KEY";
-            case AIProviderName.VERTEX:
-                return "GOOGLE_APPLICATION_CREDENTIALS";
-            case AIProviderName.GOOGLE_AI:
-                return "GOOGLE_AI_API_KEY";
-            case AIProviderName.BEDROCK:
-                return "AWS_ACCESS_KEY_ID";
-            case AIProviderName.AZURE:
-                return "AZURE_OPENAI_API_KEY";
-            case AIProviderName.LITELLM:
-                return "LITELLM_API_KEY";
-            case AIProviderName.OLLAMA:
-                return "OLLAMA_BASE_URL";
-            default:
-                return "";
-        }
+        return ProviderFactory.getDescriptor(providerName)?.envVars.apiKey ?? "";
     }
     /**
      * Validate API key format for a provider
      */
     static validateApiKeyFormat(providerName, apiKey) {
-        switch (providerName) {
-            case AIProviderName.ANTHROPIC:
-                return (apiKey.startsWith("sk-ant-") &&
-                    apiKey.length >= API_KEY_LENGTHS.ANTHROPIC_MIN);
-            case AIProviderName.OPENAI:
-                return (apiKey.startsWith("sk-") &&
-                    apiKey.length >= API_KEY_LENGTHS.OPENAI_MIN);
-            case AIProviderName.GOOGLE_AI:
-                return apiKey.length >= API_KEY_LENGTHS.GOOGLE_AI_EXACT; // Basic length check
-            case AIProviderName.VERTEX:
-                return apiKey.endsWith(".json") || apiKey.includes("type"); // JSON key format
-            case AIProviderName.BEDROCK:
-                return apiKey.length >= API_KEY_LENGTHS.AWS_ACCESS_KEY; // AWS access key length
-            case AIProviderName.AZURE:
-                return apiKey.length >= API_KEY_LENGTHS.AZURE_MIN; // Azure OpenAI API key length
-            case AIProviderName.LITELLM:
-                return apiKey.length > 0;
-            case AIProviderName.OLLAMA:
-                return true; // Ollama usually doesn't require specific format
-            default:
-                return true; // Default to true for unknown providers
+        // Vertex's "API key" is really a credentials file path (or an inline
+        // JSON blob via GOOGLE_SERVICE_ACCOUNT_KEY) — never governed by the
+        // shared API_KEY_FORMATS regexes. Preserved exactly from the original
+        // switch even though checkApiKeyValidity() early-returns before ever
+        // reaching this call for Vertex today; kept correct for any other/
+        // future caller.
+        if (providerName === AIProviderName.VERTEX) {
+            return apiKey.endsWith(".json") || apiKey.includes("type");
+        }
+        const descriptor = ProviderFactory.getDescriptor(providerName);
+        if (!descriptor?.apiKeyFormatPattern) {
+            // Providers with no documented format (or local runtimes / providers
+            // usable with zero configuration) are accepted as-is — matches the
+            // old switch's per-provider `default: true`/no-format-check branches
+            // (ollama, litellm).
+            if (descriptor?.localRuntime || descriptor?.envVars.optional) {
+                return true;
+            }
+            return apiKey.length > 0;
         }
+        return descriptor.apiKeyFormatPattern.test(apiKey);
     }
     /**
      * Get health check endpoint for connectivity testing
      */
     static getProviderHealthEndpoint(providerName) {
-        switch (providerName) {
-            case AIProviderName.ANTHROPIC:
-                return null; // Anthropic doesn't have a public health endpoint
+        const descriptor = ProviderFactory.getDescriptor(providerName);
+        if (descriptor?.healthCheck !== "models-probe") {
+            return null;
+        }
+        // OpenAI/LiteLLM/Ollama each need a provider-specific URL builder that
+        // isn't pure descriptor data (LiteLLM/Ollama depend on the configured
+        // base URL) — keep the existing per-provider dispatch for the 3
+        // models-probe providers, now gated on the descriptor instead of a
+        // hardcoded name list.
+        switch (descriptor.name) {
             case AIProviderName.OPENAI:
                 return "https://api.openai.com/v1/models";
-            case AIProviderName.GOOGLE_AI:
-                return null; // No public health endpoint
-            case AIProviderName.VERTEX:
-                return null; // Complex authentication required
-            case AIProviderName.BEDROCK:
-                return null; // AWS endpoints vary by region
             case AIProviderName.LITELLM:
                 return this.getLiteLLMModelsUrl();
             case AIProviderName.OLLAMA: