@juspay/neurolink 11.1.0 → 11.1.1

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,27 +36,25 @@ export declare class ProviderHealthChecker {
      */
     private static checkModelAvailability;
     /**
-     * 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 required environment variables for a provider
+     * 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[];
     /**
@@ -107,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
      */

package/dist/lib/utils/providerHealth.js

@@ -4,7 +4,7 @@
  */
 import { logger } from "./logger.js";
 import { AIProviderName, OpenAIModels, GoogleAIModels, AnthropicModels, BedrockModels, } from "../constants/enums.js";
-import { PROJECT_ID_FORMAT } from "./providerConfig.js";
+import { PROJECT_ID_FORMAT, satisfiesFallbacks } from "./providerConfig.js";
 import { basename } from "path";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { DEFAULT_OLLAMA_MODEL } from "../providers/ollama/constants.js";
@@ -194,7 +194,7 @@ export class ProviderHealthChecker {
             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]);
+                satisfiesFallbacks(extraRequiredFallbacks, process.env);
             logger.debug("Vertex auth final result", { hasValidAuth });
             if (hasValidAuth) {
                 healthStatus.hasApiKey = true;
@@ -342,46 +342,40 @@ 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
+     * 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) {
-        // 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
+        // Resolve the descriptor FIRST so the field check below is keyed on
+        // the canonical, alias-resolved `descriptor.credentialsResolvedExternally`
+        // — 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.
+        // field exists to prevent.
         const descriptor = ProviderFactory.getDescriptor(providerName);
         if (!descriptor) {
             return [];
         }
-        if (this.ENV_CHECK_DELEGATED_TO_SPECIFIC_CONFIG.has(descriptor.name)) {
+        if (descriptor.credentialsResolvedExternally) {
             return [];
         }
         const { apiKey, extraRequired } = descriptor.envVars;
@@ -518,11 +512,11 @@ export class ProviderHealthChecker {
             hasValidAuth = await this.checkGoogleApplicationCredentials(healthStatus);
         }
         if (!hasValidAuth) {
-            hasValidAuth = this.checkIndividualGoogleCredentials(healthStatus);
+            hasValidAuth = this.checkExtraRequiredFallbackCredentials(healthStatus);
         }
         if (!hasValidAuth) {
             healthStatus.configurationIssues.push("Google Cloud authentication not configured or credentials file missing");
-            healthStatus.recommendations.push("Set either GOOGLE_APPLICATION_CREDENTIALS (valid file path), GOOGLE_SERVICE_ACCOUNT_KEY (base64), or both GOOGLE_AUTH_CLIENT_EMAIL and GOOGLE_AUTH_PRIVATE_KEY");
+            healthStatus.recommendations.push("Set either GOOGLE_APPLICATION_CREDENTIALS (valid file path), GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK, GOOGLE_SERVICE_ACCOUNT_KEY (base64), or both GOOGLE_AUTH_CLIENT_EMAIL and GOOGLE_AUTH_PRIVATE_KEY");
         }
         return hasValidAuth;
     }
@@ -554,13 +548,20 @@ export class ProviderHealthChecker {
         }
     }
     /**
-     * Check individual Google credentials
+     * 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.
      */
-    static checkIndividualGoogleCredentials(healthStatus) {
-        const hasServiceAccountKey = !!process.env.GOOGLE_SERVICE_ACCOUNT_KEY;
-        const hasIndividualCredentials = !!(process.env.GOOGLE_AUTH_CLIENT_EMAIL &&
-            process.env.GOOGLE_AUTH_PRIVATE_KEY);
-        if (hasServiceAccountKey || hasIndividualCredentials) {
+    static checkExtraRequiredFallbackCredentials(healthStatus) {
+        const descriptor = ProviderFactory.getDescriptor(AIProviderName.VERTEX);
+        const hasValidAuth = satisfiesFallbacks(descriptor?.envVars.extraRequiredFallbacks, process.env);
+        if (hasValidAuth) {
             healthStatus.hasApiKey = true;
             return true;
         }

package/dist/lib/utils/providerUtils.js

@@ -6,7 +6,7 @@ import { AIProviderFactory } from "../core/factory.js";
 import { logger } from "./logger.js";
 import { AIProviderName } from "../constants/enums.js";
 import { ProviderHealthChecker } from "./providerHealth.js";
-import { API_KEY_FORMATS, API_KEY_LENGTHS, PROJECT_ID_FORMAT, } from "./providerConfig.js";
+import { API_KEY_FORMATS, API_KEY_LENGTHS, PROJECT_ID_FORMAT, satisfiesFallbacks, } from "./providerConfig.js";
 import { DEFAULT_OLLAMA_MODEL } from "../providers/ollama/constants.js";
 import { ProviderFactory } from "../factories/providerFactory.js";
 import { PROVIDER_DESCRIPTORS } from "../factories/providerDescriptors.js";
@@ -340,7 +340,7 @@ export function hasProviderEnvVars(provider) {
         return false;
     }
     return ((extraRequired ?? []).every((v) => !!process.env[v]) ||
-        (extraRequiredFallbacks ?? []).some((v) => !!process.env[v]));
+        satisfiesFallbacks(extraRequiredFallbacks, process.env));
 }
 /**
  * Get available provider names

package/dist/processors/base/BaseFileProcessor.d.ts

@@ -45,6 +45,23 @@
  */
 import { FileErrorCode } from "../errors/index.js";
 import type { BatchProcessingSummary, FileInfo, FileProcessingError, ProcessorFileProcessingResult, FileProcessorConfig, ProcessorOperationResult, ProcessedFileBase, ProcessOptions } from "../../types/index.js";
+/**
+ * Marker on the error raised when a processor refuses content for exceeding
+ * the size limit *after* the download — a ZIP entry that expands past the
+ * bound, say.
+ *
+ * Separate from DOWNLOAD_TOO_LARGE because the two fire at different stages,
+ * but it exists for the same reason. Without it a bound that fires reaches
+ * `buildProcessedResultWithResult` as a plain Error and becomes
+ * PROCESSING_FAILED, which is `retryable: true` — so a caller retries a
+ * deterministic refusal three times and gets the identical answer each time.
+ * FILE_TOO_LARGE is `retryable: false`, which is the truth about this failure.
+ */
+export declare const CONTENT_TOO_LARGE_CODE = "CONTENT_TOO_LARGE";
+/** An error that a processor's own size bound was exceeded. */
+export declare function contentTooLargeError(message: string): Error;
+/** Whether `error` is a processor size bound firing rather than a fault. */
+export declare function isContentTooLarge(error: unknown): boolean;
 /**
  * Abstract base class for file processors.
  * Provides common download, validation, and error handling functionality.

package/dist/processors/base/BaseFileProcessor.js

@@ -72,6 +72,29 @@ function downloadTooLargeError(maxSizeMB, typeName) {
 function isDownloadTooLarge(error) {
     return (error?.code === DOWNLOAD_TOO_LARGE_CODE);
 }
+/**
+ * Marker on the error raised when a processor refuses content for exceeding
+ * the size limit *after* the download — a ZIP entry that expands past the
+ * bound, say.
+ *
+ * Separate from DOWNLOAD_TOO_LARGE because the two fire at different stages,
+ * but it exists for the same reason. Without it a bound that fires reaches
+ * `buildProcessedResultWithResult` as a plain Error and becomes
+ * PROCESSING_FAILED, which is `retryable: true` — so a caller retries a
+ * deterministic refusal three times and gets the identical answer each time.
+ * FILE_TOO_LARGE is `retryable: false`, which is the truth about this failure.
+ */
+export const CONTENT_TOO_LARGE_CODE = "CONTENT_TOO_LARGE";
+/** An error that a processor's own size bound was exceeded. */
+export function contentTooLargeError(message) {
+    const error = new Error(message);
+    error.code = CONTENT_TOO_LARGE_CODE;
+    return error;
+}
+/** Whether `error` is a processor size bound firing rather than a fault. */
+export function isContentTooLarge(error) {
+    return (error?.code === CONTENT_TOO_LARGE_CODE);
+}
 /** Node's signal that a zlib output bound was reached. */
 function isBufferTooLargeError(error) {
     return (error?.code === "ERR_BUFFER_TOO_LARGE");
@@ -360,6 +383,23 @@ export class BaseFileProcessor {
             return { success: true, data: result };
         }
         catch (error) {
+            // A size bound firing is a verdict, not a fault: PROCESSING_FAILED is
+            // retryable, and re-running a decompression that will hit the same
+            // ceiling is the one thing worth not doing three times.
+            if (isContentTooLarge(error)) {
+                return {
+                    success: false,
+                    // Same detail keys as the other FILE_TOO_LARGE sites, so anything
+                    // reading them does not have to special-case where the verdict came
+                    // from. `sizeMB` is absent on purpose: the decompressed size is the
+                    // number this bound exists to never find out.
+                    error: this.createError(FileErrorCode.FILE_TOO_LARGE, {
+                        maxMB: this.config.maxSizeMB,
+                        type: this.config.fileTypeName,
+                        reason: error instanceof Error ? error.message : undefined,
+                    }),
+                };
+            }
             return {
                 success: false,
                 error: this.createError(FileErrorCode.PROCESSING_FAILED, { fileType: this.config.fileTypeName }, error instanceof Error ? error : undefined),

package/dist/processors/document/OpenDocumentProcessor.js

@@ -8,7 +8,7 @@
  */
 import { createRequire } from "node:module";
 import * as zlib from "node:zlib";
-import { BaseFileProcessor } from "../base/BaseFileProcessor.js";
+import { BaseFileProcessor, contentTooLargeError, isContentTooLarge, } from "../base/BaseFileProcessor.js";
 import { readZipEntryWithinLimit } from "../archive/zipEntryReader.js";
 import { SIZE_LIMITS } from "../config/index.js";
 const require = createRequire(import.meta.url);
@@ -71,7 +71,10 @@ export class OpenDocumentProcessor extends BaseFileProcessor {
                 // `maxSizeMB` only ever saw the compressed archive on the way in.
                 const read = readZipEntryWithinLimit(contentEntry, SIZE_LIMITS.DOCUMENT_MAX_MB * 1024 * 1024, zlib);
                 if (read.status === "too-large") {
-                    throw new Error(`content.xml exceeds the ${SIZE_LIMITS.DOCUMENT_MAX_MB}MB limit for OpenDocument content`);
+                    // Coded, so the bound surfaces as FILE_TOO_LARGE (not retryable)
+                    // rather than PROCESSING_FAILED (retryable). The file will be
+                    // exactly as oversized on the next attempt.
+                    throw contentTooLargeError(`content.xml in "${this.getFilename(fileInfo)}" exceeds the ${SIZE_LIMITS.DOCUMENT_MAX_MB}MB limit for OpenDocument content`);
                 }
                 if (read.status !== "ok") {
                     throw new Error("content.xml could not be read from the archive");
@@ -93,6 +96,13 @@ export class OpenDocumentProcessor extends BaseFileProcessor {
             }
         }
         catch (error) {
+            // A size verdict passes through intact. Re-wrapping it as a plain Error
+            // drops the code, and the base class then reports PROCESSING_FAILED —
+            // which is retryable, so the caller would refetch and decompress a file
+            // guaranteed to be exactly as oversized.
+            if (isContentTooLarge(error)) {
+                throw error;
+            }
             const message = error instanceof Error ? error.message : "Unknown error";
             throw new Error(`Failed to extract OpenDocument content: ${message}`, {
                 cause: error,

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

@@ -1714,8 +1714,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 +1741,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

@@ -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/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
 // =============================================================================