@juspay/neurolink 11.1.0 → 11.2.0

package/dist/providers/openaiCompatCatalog.js

@@ -0,0 +1,271 @@
+import { AIProviderName } from "../constants/enums.js";
+import { CloudflareModels, FireworksModels, GroqModels, MistralModels, PerplexityModels, TogetherAIModels, XaiModels, } from "../constants/enums.js";
+import { AuthenticationError, InvalidModelError, ProviderError, } from "../types/index.js";
+import { DEFAULT_ERROR_RULES } from "../utils/errorClassifier.js";
+import { createCloudflareConfig, createFireworksConfig, createGroqConfig, createMistralConfig, createPerplexityConfig, createTogetherAIConfig, createXaiConfig, } from "../utils/providerConfig.js";
+function buildCloudflareBaseURL(accountId) {
+    return `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1`;
+}
+/**
+ * Config-driven catalog of the 7 zero-quirk OpenAI-compatible providers.
+ * Each entry fully replaces what used to be a hand-written
+ * OpenAIChatCompletionsProvider subclass — see ConfiguredOpenAICompatProvider
+ * for the class that reads these entries, and providerRegistry.ts for the
+ * registration loop that consumes this array.
+ *
+ * `errorRules` mirrors each provider's LIVE `formatProviderError` rule array
+ * (post plan-07/wave-2 migration), not the original hand-rolled ladder these
+ * providers had when plan 05 was first drafted: every provider below now
+ * keeps only its bespoke rule(s) — auth, plus Groq's model_decommissioned and
+ * xAI's insufficient_quota — before spreading the SAME exported
+ * `DEFAULT_ERROR_RULES` constant that the live subclasses spread (never an
+ * inlined copy, so this catalog cannot drift from that table independently).
+ * See plan-05/progress.md Ruling R4 for the full rationale.
+ *
+ * To add a new zero-quirk OpenAI-compatible provider: add one entry here.
+ * Do NOT add a provider here if it needs any hook override beyond the 3
+ * mandatory ones (getProviderName/getDefaultModel/formatProviderError) —
+ * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts, and
+ * Task 14's docs task for the deciding criteria).
+ */
+export const OPENAI_COMPAT_CATALOG = [
+    {
+        providerName: AIProviderName.GROQ,
+        aliases: ["groq"],
+        apiKeyEnvVar: "GROQ_API_KEY",
+        baseURLEnvVar: "GROQ_BASE_URL",
+        defaultBaseURL: "https://api.groq.com/openai/v1",
+        configOptions: createGroqConfig(),
+        modelEnvVar: "GROQ_MODEL",
+        defaultModel: GroqModels.LLAMA_3_3_70B_VERSATILE,
+        registryDefaultModel: GroqModels.LLAMA_3_3_70B_VERSATILE,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: GroqModels.LLAMA_3_1_8B_INSTANT,
+        fallbackModels: [
+            GroqModels.LLAMA_3_3_70B_VERSATILE,
+            GroqModels.LLAMA_3_1_8B_INSTANT,
+            GroqModels.GEMMA_2_9B_IT,
+            GroqModels.MIXTRAL_8X7B_32768,
+            GroqModels.LLAMA_3_2_90B_VISION_PREVIEW,
+            GroqModels.LLAMA_3_2_11B_VISION_PREVIEW,
+        ],
+        // KNOWN GAP (not reproducible by this data-only array — flagged for PR C,
+        // see plan-05/task-A-report.md): live GroqProvider.formatProviderError()
+        // intercepts TimeoutError and returns a plain ProviderError BEFORE ever
+        // calling classifyProviderError, overriding that function's own
+        // (non-overridable) rule that TimeoutError always maps to NetworkError.
+        // ConfiguredOpenAICompatProvider.formatProviderError() has no such
+        // pre-check hook, so migrating Groq onto it as-is would silently
+        // reclassify Groq timeouts as NetworkError. This entry's errorRules
+        // still mirrors Groq's live rule array faithfully for every other error
+        // shape; the TimeoutError special case is a structural gap in
+        // ConfiguredOpenAICompatProvider, not a data error here.
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication|invalid_api_key/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Groq API key. Check GROQ_API_KEY. Get one at https://console.groq.com/keys",
+            },
+            {
+                match: (ctx) => /model_decommissioned/i.test(ctx.message),
+                errorClass: InvalidModelError,
+                message: (ctx) => `Groq model '${ctx.modelName}' was decommissioned. Pick a current model from https://console.groq.com/docs/models.`,
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.XAI,
+        aliases: ["xai", "grok"],
+        apiKeyEnvVar: "XAI_API_KEY",
+        baseURLEnvVar: "XAI_BASE_URL",
+        defaultBaseURL: "https://api.x.ai/v1",
+        configOptions: createXaiConfig(),
+        modelEnvVar: "XAI_MODEL",
+        defaultModel: XaiModels.GROK_3,
+        registryDefaultModel: XaiModels.GROK_3,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: XaiModels.GROK_3_MINI,
+        fallbackModels: [
+            XaiModels.GROK_3,
+            XaiModels.GROK_3_MINI,
+            XaiModels.GROK_2_LATEST,
+            XaiModels.GROK_2_VISION_LATEST,
+            XaiModels.GROK_BETA,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication|invalid_api_key/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid xAI API key. Please check your XAI_API_KEY environment variable. Get one at https://console.x.ai/",
+            },
+            {
+                match: (ctx) => /insufficient_quota|quota exceeded/i.test(ctx.message),
+                errorClass: ProviderError,
+                message: "xAI account has insufficient quota. Top up at https://console.x.ai/",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.TOGETHER_AI,
+        aliases: ["together-ai", "together"],
+        apiKeyEnvVar: "TOGETHER_API_KEY",
+        baseURLEnvVar: "TOGETHER_BASE_URL",
+        defaultBaseURL: "https://api.together.xyz/v1",
+        configOptions: createTogetherAIConfig(),
+        modelEnvVar: "TOGETHER_MODEL",
+        defaultModel: TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
+        registryDefaultModel: TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: TogetherAIModels.LLAMA_3_1_8B_INSTRUCT_TURBO,
+        fallbackModels: [
+            TogetherAIModels.LLAMA_3_3_70B_INSTRUCT_TURBO,
+            TogetherAIModels.LLAMA_3_1_405B_INSTRUCT_TURBO,
+            TogetherAIModels.LLAMA_3_1_70B_INSTRUCT_TURBO,
+            TogetherAIModels.LLAMA_3_1_8B_INSTRUCT_TURBO,
+            TogetherAIModels.MIXTRAL_8X22B_INSTRUCT,
+            TogetherAIModels.QWEN_2_5_72B_INSTRUCT_TURBO,
+            TogetherAIModels.DEEPSEEK_R1,
+            TogetherAIModels.DEEPSEEK_V3,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Together AI API key. Get one at https://api.together.xyz/settings/api-keys",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.FIREWORKS,
+        aliases: ["fireworks"],
+        apiKeyEnvVar: "FIREWORKS_API_KEY",
+        baseURLEnvVar: "FIREWORKS_BASE_URL",
+        defaultBaseURL: "https://api.fireworks.ai/inference/v1",
+        configOptions: createFireworksConfig(),
+        modelEnvVar: "FIREWORKS_MODEL",
+        defaultModel: FireworksModels.DEEPSEEK_V4_PRO,
+        registryDefaultModel: FireworksModels.DEEPSEEK_V4_PRO,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: FireworksModels.DEEPSEEK_V4_PRO,
+        fallbackModels: [
+            FireworksModels.DEEPSEEK_V4_PRO,
+            FireworksModels.GLM_5P1,
+            FireworksModels.GLM_5,
+            FireworksModels.KIMI_K2P6,
+            FireworksModels.KIMI_K2P5,
+            FireworksModels.GPT_OSS_120B,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Fireworks API key. Get one at https://fireworks.ai/account/api-keys",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.PERPLEXITY,
+        aliases: ["perplexity", "pplx"],
+        apiKeyEnvVar: "PERPLEXITY_API_KEY",
+        baseURLEnvVar: "PERPLEXITY_BASE_URL",
+        defaultBaseURL: "https://api.perplexity.ai",
+        configOptions: createPerplexityConfig(),
+        modelEnvVar: "PERPLEXITY_MODEL",
+        defaultModel: PerplexityModels.SONAR,
+        registryDefaultModel: PerplexityModels.SONAR,
+        registryDefaultModelChecksEnvVar: true,
+        // Perplexity's live class does NOT override getFallbackModelName() — it
+        // inherits the base class default "gpt-3.5-turbo". Preserved here
+        // verbatim, not "fixed" to a Perplexity model — that's a real,
+        // pre-existing quirk this plan is not authorized to change.
+        fallbackModelName: "gpt-3.5-turbo",
+        fallbackModels: [
+            PerplexityModels.SONAR,
+            PerplexityModels.SONAR_PRO,
+            PerplexityModels.SONAR_REASONING,
+            PerplexityModels.SONAR_REASONING_PRO,
+            PerplexityModels.SONAR_DEEP_RESEARCH,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Perplexity API key. Get one at https://www.perplexity.ai/settings/api",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.MISTRAL,
+        aliases: ["mistral"],
+        apiKeyEnvVar: "MISTRAL_API_KEY",
+        baseURLEnvVar: "MISTRAL_BASE_URL",
+        defaultBaseURL: "https://api.mistral.ai/v1",
+        configOptions: createMistralConfig(),
+        modelEnvVar: "MISTRAL_MODEL",
+        defaultModel: MistralModels.MISTRAL_SMALL_2506,
+        // The one documented registry-vs-class default-model quirk (see this
+        // plan's "Design reference" section): the registry passes the bare
+        // literal MISTRAL_LARGE_LATEST with no env-var check, while
+        // MistralProvider.getDefaultModel() checks MISTRAL_MODEL and defaults to
+        // MISTRAL_SMALL_2506. Preserved exactly, not reconciled.
+        registryDefaultModel: MistralModels.MISTRAL_LARGE_LATEST,
+        registryDefaultModelChecksEnvVar: false,
+        fallbackModelName: MistralModels.MISTRAL_SMALL_2506,
+        fallbackModels: [
+            MistralModels.MISTRAL_SMALL_2506,
+            MistralModels.MISTRAL_LARGE_LATEST,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /API_KEY_INVALID|Invalid API key|Unauthorized/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Mistral API key. Please check your MISTRAL_API_KEY environment variable.",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+    {
+        providerName: AIProviderName.CLOUDFLARE,
+        aliases: ["cloudflare", "workers-ai", "cf-ai"],
+        apiKeyEnvVar: "CLOUDFLARE_API_KEY",
+        computedBaseURL: {
+            envVar: "CLOUDFLARE_ACCOUNT_ID",
+            missingValueMessage: "CLOUDFLARE_ACCOUNT_ID is required (or pass credentials.cloudflare.accountId). Get the account id from https://dash.cloudflare.com/",
+            build: buildCloudflareBaseURL,
+        },
+        configOptions: createCloudflareConfig(),
+        modelEnvVar: "CLOUDFLARE_MODEL",
+        defaultModel: CloudflareModels.LLAMA_3_3_70B_FAST,
+        registryDefaultModel: CloudflareModels.LLAMA_3_3_70B_FAST,
+        registryDefaultModelChecksEnvVar: true,
+        fallbackModelName: CloudflareModels.LLAMA_3_1_8B_FAST,
+        fallbackModels: [
+            CloudflareModels.LLAMA_3_3_70B_FAST,
+            CloudflareModels.LLAMA_3_1_70B_INSTRUCT,
+            CloudflareModels.LLAMA_3_1_8B_FAST,
+            CloudflareModels.LLAMA_3_2_11B_VISION,
+            CloudflareModels.MISTRAL_7B_INSTRUCT_V0_2,
+            CloudflareModels.QWEN_1P5_14B_CHAT_AWQ,
+        ],
+        errorRules: [
+            {
+                match: (ctx) => ctx.statusCode === 401 ||
+                    /Invalid API key|Authentication/i.test(ctx.message),
+                errorClass: AuthenticationError,
+                message: "Invalid Cloudflare API key. Use a token with Workers AI Read+Write scope. Get one at https://dash.cloudflare.com/profile/api-tokens",
+            },
+            ...DEFAULT_ERROR_RULES,
+        ],
+    },
+];

package/dist/proxy/proxyFetch.js

@@ -8,6 +8,7 @@ import { SpanStatusCode, propagation, context } from "@opentelemetry/api";
 import { tracers } from "../telemetry/tracers.js";
 import { shouldBypassProxy } from "./utils/noProxyUtils.js";
 import { createHash } from "node:crypto";
+import { TRANSIENT_NETWORK_CODES } from "../constants/networkErrorCodes.js";
 async function getLangfuseContext() {
     try {
         // Dynamic import to avoid hard dependency — getLangfuseContext is only
@@ -79,15 +80,6 @@ function extractHostname(url) {
         return "[unknown]";
     }
 }
-/** Error codes classified as transient (module-scope: the retry path is hot). */
-const TRANSIENT_NETWORK_CODES = new Set([
-    "ECONNRESET",
-    "ETIMEDOUT",
-    "ECONNREFUSED",
-    "EPIPE",
-    "UND_ERR_SOCKET",
-    "UND_ERR_CONNECT_TIMEOUT",
-]);
 /**
  * Classify a fetch failure as a transient network error worth retrying.
  *

package/dist/types/cli.d.ts

@@ -583,6 +583,8 @@ export type SetupArgs = {
     status?: boolean;
     interactive?: boolean;
     help?: boolean;
+    check?: boolean;
+    nonInteractive?: boolean;
 };
 /**
  * Narrowed ProviderInfo used by the main `neurolink setup` command,

package/dist/types/providers.d.ts

@@ -8,6 +8,7 @@ import type { ValidationSchema } from "./aliases.js";
 import type { EnhancedGenerateResult, GenerateResult, TextGenerationOptions } from "./generate.js";
 import type { MultimodalAudioEntry } from "./file.js";
 import type { StreamOptions, StreamResult } from "./stream.js";
+import type { ProviderErrorRule } from "./errors.js";
 import type { ExternalMCPToolInfo } from "./externalMcp.js";
 import type { ClaudeSubscriptionTier, AnthropicAuthMethod, AnthropicAuthConfig, SubscriptionInfo, OAuthToken } from "./subscription.js";
 import type { Tool } from "./tools.js";
@@ -577,6 +578,104 @@ export type ProviderConfigOptions = {
     fallbackEnvVars?: string[];
     optional?: boolean;
 };
+/**
+ * Minimal credential shape accepted by resolveOpenAICompatConfig() and
+ * ConfiguredOpenAICompatProvider. A structural superset of every real
+ * per-provider NeurolinkCredentials["<key>"] slice in this family (groq,
+ * xai, together, fireworks, perplexity, mistral, cloudflare) — all fields
+ * optional, so passing e.g. NeurolinkCredentials["groq"] (which has no
+ * accountId) here is always structurally valid.
+ */
+export type OpenAICompatCredentials = {
+    apiKey?: string;
+    baseURL?: string;
+    accountId?: string;
+};
+/**
+ * One row of the config-driven OpenAI-compatible provider catalog
+ * (OPENAI_COMPAT_CATALOG, src/lib/providers/openaiCompatCatalog.ts).
+ * Replaces a hand-written OpenAIChatCompletionsProvider subclass for
+ * providers whose only differences from every sibling are credentials,
+ * base URL, model defaults, and error-message classification.
+ */
+export type OpenAICompatCatalogEntry = {
+    /** Registry key / nl.generate({provider}) value, e.g. "groq". */
+    providerName: AIProviderName;
+    /** Registry aliases, e.g. ["together-ai", "together"]. */
+    aliases: string[];
+    /**
+     * Env var holding the API key, e.g. "GROQ_API_KEY".
+     *
+     * Declarative: the key is actually read through `configOptions.envVarName`,
+     * which `validateApiKey` consults. This field exists so an entry states its
+     * credential source without a caller having to reach into configOptions,
+     * and the catalog suite asserts the two always name the same variable — two
+     * fields describing one fact are worth nothing if they can disagree.
+     */
+    apiKeyEnvVar: string;
+    /**
+     * Env var that can override the base URL, e.g. "GROQ_BASE_URL". Omit
+     * for entries that use computedBaseURL instead (e.g. Cloudflare).
+     */
+    baseURLEnvVar?: string;
+    /** Static default base URL. Omit for computedBaseURL entries. */
+    defaultBaseURL?: string;
+    /**
+     * Present only for providers whose base URL is computed from an extra
+     * required credential value instead of a static default (Cloudflare's
+     * accountId). Deliberately narrow (accountId-shaped) rather than a
+     * generic extra-field mechanism — Cloudflare is the only current user.
+     */
+    computedBaseURL?: {
+        /** Env var fallback for the extra value, e.g. "CLOUDFLARE_ACCOUNT_ID". */
+        envVar: string;
+        /** Thrown when neither credentials.accountId nor envVar supply a value. */
+        missingValueMessage: string;
+        /** Builds the base URL from the resolved accountId. */
+        build: (accountId: string) => string;
+    };
+    /** Setup/help metadata, passed to validateApiKey(). Not consumed by
+     *  classifyProviderError() — that function's ProviderErrorContext has no
+     *  docsUrl field; any URL a rule's message needs is inlined in the rule
+     *  itself (see Task 4). */
+    configOptions: ProviderConfigOptions;
+    /** Env var for the default model, e.g. "GROQ_MODEL". */
+    modelEnvVar: string;
+    /** Default model when modelEnvVar is unset. */
+    defaultModel: string;
+    /**
+     * The literal passed as ProviderFactory.registerProvider()'s defaultModel
+     * argument (resolved before the provider is constructed). Preserves each
+     * provider's exact pre-migration registry behavior.
+     */
+    registryDefaultModel: string;
+    /**
+     * True for every provider except Mistral: whether the registry-level
+     * default also consults modelEnvVar before falling back to
+     * registryDefaultModel. False is a pre-existing, intentionally-preserved
+     * quirk unique to Mistral's registration (see plan's Design reference).
+     */
+    registryDefaultModelChecksEnvVar: boolean;
+    /** Fallback model name (getFallbackModelName()). */
+    fallbackModelName: string;
+    /** Fallback model list (getFallbackModels()). */
+    fallbackModels: string[];
+    /**
+     * Error-classification rules, consumed by classifyProviderError. Typed
+     * as a mutable array — not readonly — because plan 07's
+     * `classifyProviderError(error, rules: ProviderErrorRule[], provider, modelName?)`
+     * declares `rules` as `ProviderErrorRule[]`; a `readonly` array here
+     * would not be assignable to that parameter without a cast, which rule
+     * 14 (no double assertions) and general hygiene both rule out. Each
+     * entry's array is still constructed as a fresh literal per provider in
+     * Task 4, so nothing actually mutates it at runtime.
+     */
+    errorRules: ProviderErrorRule[];
+};
+/** The subset of OpenAICompatCatalogEntry that resolveOpenAICompatConfig()
+ *  needs — lets call sites pass a minimal object without the full catalog
+ *  entry (e.g. in tests, or a future non-catalog caller). */
+export type OpenAICompatConfigInput = Pick<OpenAICompatCatalogEntry, "providerName" | "apiKeyEnvVar" | "baseURLEnvVar" | "defaultBaseURL" | "computedBaseURL" | "configOptions">;
 /**
  * AI Provider type with flexible parameter support
  */
@@ -1714,8 +1813,8 @@ export type ProviderDescriptor = {
         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[];
+        /** 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;
     };
@@ -1741,6 +1840,21 @@ export type ProviderDescriptor = {
     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/utils/errorClassifier.js

@@ -13,21 +13,84 @@
 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 record = error && typeof error === "object"
-        ? error
-        : undefined;
-    const message = typeof record?.message === "string"
-        ? record.message
+    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: duckTypedStatusCode(error),
-        errorName: typeof record?.name === "string" ? record.name : undefined,
-        errorCode: typeof record?.code === "string" ? record.code : undefined,
+        statusCode,
+        errorName: firstString(chain, "name"),
+        errorCode: firstString(chain, "code"),
         provider,
         modelName,
     };
@@ -80,13 +143,39 @@ export const DEFAULT_ERROR_RULES = [
             : `${ctx.provider} model not found.`,
     },
     {
-        match: (ctx) => /ECONNRESET|ENOTFOUND|ECONNREFUSED|ETIMEDOUT|network|connection/i.test(ctx.message),
+        // 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}`,
     },
     {
-        match: (ctx) => (ctx.statusCode !== undefined && ctx.statusCode >= 500) ||
-            /\b5\d\d\b|server error/i.test(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}`,
     },

package/dist/utils/providerConfig.d.ts

@@ -5,7 +5,7 @@
  * Enhanced with format validation and advanced error classification
  * Extended with Claude subscription OAuth support
  */
-import type { APIValidationResult, ProviderConfigOptions, AnthropicAuthMethod, ClaudeSubscriptionTier, AnthropicAuthConfig, AnthropicAuthConfigResult } from "../types/index.js";
+import type { APIValidationResult, ProviderConfigOptions, AnthropicAuthMethod, ClaudeSubscriptionTier, AnthropicAuthConfig, AnthropicAuthConfigResult, OpenAICompatConfigInput, OpenAICompatCredentials } from "../types/index.js";
 /**
  * API key format validation patterns (extracted from advanced validation system)
  * Exported for use across the codebase to replace scattered regex patterns
@@ -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
@@ -353,3 +369,25 @@ export declare function hasSubscriptionFeature(feature: "extended_thinking" | "p
  * @returns Human-readable configuration description
  */
 export declare function describeAnthropicConfig(): string;
+/**
+ * Resolves the {apiKey, baseURL} pair for a config-driven OpenAI-compatible
+ * catalog entry (see OpenAICompatCatalogEntry in types/providers.ts).
+ *
+ * Extracted from the identical 6-line precedence block that was copy-pasted
+ * across groq.ts, xai.ts, togetherAi.ts, fireworks.ts, perplexity.ts, and
+ * mistral.ts, plus Cloudflare's accountId-computed-baseURL variant.
+ *
+ * Precedence (matches every ported subclass's original behavior exactly):
+ *   apiKey:  credentials.apiKey (trimmed, non-blank) > env var > throw
+ *   baseURL: credentials.baseURL (trimmed, non-blank)
+ *            > env var (if entry.baseURLEnvVar is set, trimmed, non-blank)
+ *            > entry.defaultBaseURL
+ *   baseURL (computedBaseURL entries, e.g. Cloudflare):
+ *            credentials.baseURL > computedBaseURL.build(accountId), where
+ *            accountId = credentials.accountId (trimmed) > env var (trimmed)
+ *            > throw computedBaseURL.missingValueMessage
+ */
+export declare function resolveOpenAICompatConfig(entry: OpenAICompatConfigInput, credentials?: OpenAICompatCredentials): {
+    apiKey: string;
+    baseURL: string;
+};