@juspay/neurolink 11.1.0 → 11.1.1

package/dist/cli/commands/setup.d.ts

@@ -28,4 +28,7 @@ export declare function checkExistingConfigurations(): Promise<string[]>;
 /**
  * Delegate to existing provider setup commands
  */
-export declare function delegateToProviderSetup(providerId: string): Promise<void>;
+export declare function delegateToProviderSetup(providerId: string, flags?: {
+    check?: boolean;
+    nonInteractive?: boolean;
+}): Promise<void>;

package/dist/cli/commands/setup.js

@@ -20,7 +20,7 @@ import { handleGCPSetup } from "./setup-gcp.js";
 import { handleHuggingFaceSetup } from "./setup-huggingface.js";
 import { handleMistralSetup } from "./setup-mistral.js";
 import { PROVIDER_DESCRIPTORS_BY_NAME } from "../../lib/factories/providerDescriptors.js";
-import { createCloudflareConfig, createCohereConfig, createDeepSeekConfig, createFireworksConfig, createGroqConfig, createIdeogramConfig, createJinaConfig, createNvidiaNimConfig, createOpenAICompatibleConfig, createPerplexityConfig, createRecraftConfig, createReplicateConfig, createStabilityConfig, createTogetherAIConfig, createVoyageConfig, createXaiConfig, } from "../../lib/utils/providerConfig.js";
+import { createCloudflareConfig, createCohereConfig, createDeepSeekConfig, createFireworksConfig, createGroqConfig, createIdeogramConfig, createJinaConfig, createNvidiaNimConfig, createOpenAICompatibleConfig, createPerplexityConfig, createRecraftConfig, createReplicateConfig, createStabilityConfig, createTogetherAIConfig, createVoyageConfig, createXaiConfig, satisfiesFallbacks, } from "../../lib/utils/providerConfig.js";
 // Provider information database
 const PROVIDERS = [
     {
@@ -277,15 +277,22 @@ function printGenericProviderSetup(providerId, config) {
  */
 export async function handleSetup(argv) {
     try {
-        // Handle specific flags
+        // Handle specific flags. `--list`/`--status` are documented as one-shot,
+        // non-interactive informational commands (see the `setup --list` /
+        // `setup --status` examples in setupCommandFactory.ts) — pass
+        // interactive: false so they print and return instead of chaining into
+        // the wizard's follow-up inquirer prompt below.
         if (argv.list) {
-            return await showProviderList();
+            return await showProviderList(false);
         }
         if (argv.status) {
-            return await showProviderStatus();
+            return await showProviderStatus(false);
         }
         if (argv.provider && argv.provider !== "auto") {
-            return await delegateToProviderSetup(argv.provider);
+            return await delegateToProviderSetup(argv.provider, {
+                check: argv.check,
+                nonInteractive: argv.nonInteractive,
+            });
         }
         // Main setup wizard
         await showWelcomeScreen();
@@ -399,7 +406,7 @@ export async function checkExistingConfigurations() {
             continue;
         }
         const requiredOk = (extraRequired ?? []).every((v) => !!process.env[v]) ||
-            (extraRequiredFallbacks ?? []).some((v) => !!process.env[v]);
+            satisfiesFallbacks(extraRequiredFallbacks, process.env);
         if (requiredOk) {
             configured.push(p.id);
         }
@@ -482,11 +489,16 @@ async function runProviderSelection() {
 /**
  * Delegate to existing provider setup commands
  */
-export async function delegateToProviderSetup(providerId) {
+export async function delegateToProviderSetup(providerId, flags = {
+    check: false,
+    nonInteractive: false,
+}) {
+    const nonInteractive = flags.nonInteractive ?? false;
+    const check = flags.check ?? false;
     const setupArgs = {
-        nonInteractive: false,
-        "non-interactive": false,
-        check: false,
+        nonInteractive,
+        "non-interactive": nonInteractive,
+        check,
         _: [],
         $0: "neurolink",
     };
@@ -580,9 +592,15 @@ async function showSetupCompletion(providerId) {
     logger.always(chalk.blue("Happy generating! 🚀"));
 }
 /**
- * Show detailed provider information
+ * Show detailed provider information.
+ *
+ * @param interactive - When true (the default, used by the interactive
+ * wizard's "learn more" menu choice), follows up with a prompt offering to
+ * launch the setup wizard. When false (used by the direct `setup --list`
+ * flag), returns immediately after printing so the command exits cleanly
+ * without waiting on stdin.
  */
-async function showProviderList() {
+async function showProviderList(interactive = true) {
     logger.always(chalk.blue("📚 NeuroLink Supported AI Providers"));
     logger.always("");
     for (const provider of PROVIDERS) {
@@ -612,6 +630,9 @@ async function showProviderList() {
     logger.always("• neurolink setup --provider azure");
     logger.always("• neurolink setup --provider bedrock");
     logger.always("");
+    if (!interactive) {
+        return;
+    }
     const { action } = await inquirer.prompt([
         {
             type: "select",
@@ -628,9 +649,15 @@ async function showProviderList() {
     }
 }
 /**
- * Show provider status with detailed information
+ * Show provider status with detailed information.
+ *
+ * @param interactive - When true (the default, used by the interactive
+ * wizard's "check status" menu choice), follows up with a prompt offering to
+ * set up another provider. When false (used by the direct `setup --status`
+ * flag), returns immediately after printing so the command exits cleanly
+ * without waiting on stdin.
  */
-async function showProviderStatus() {
+async function showProviderStatus(interactive = true) {
     const spinner = ora("🔍 Checking all AI provider configurations...").start();
     try {
         // Get provider status using NeuroLink SDK
@@ -691,6 +718,9 @@ async function showProviderStatus() {
             logger.always("• Check performance: neurolink provider status");
             logger.always("");
         }
+        if (!interactive) {
+            return;
+        }
         const { setupAnother } = await inquirer.prompt([
             {
                 type: "confirm",

package/dist/constants/networkErrorCodes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error codes that indicate a transient transport failure (dropped
+ * connection, socket reset, connect timeout) rather than a permanent
+ * misconfiguration. Shared between `proxy/proxyFetch.ts` (retry gating) and
+ * `utils/errorClassifier.ts` (NetworkError classification) so both stay in
+ * sync — a second hand-maintained copy would drift the two apart the same
+ * way the "5xx literal text vs statusCode" split did.
+ *
+ * undici's native `fetch()` wraps the real transport failure in
+ * `TypeError: fetch failed`, with the actionable code on `error.cause`
+ * (sometimes nested another level deep, e.g. a SocketError inside a
+ * ConnectTimeoutError) — never on the outer TypeError itself.
+ */
+export declare const TRANSIENT_NETWORK_CODES: ReadonlySet<string>;

package/dist/constants/networkErrorCodes.js

@@ -0,0 +1,21 @@
+/**
+ * Error codes that indicate a transient transport failure (dropped
+ * connection, socket reset, connect timeout) rather than a permanent
+ * misconfiguration. Shared between `proxy/proxyFetch.ts` (retry gating) and
+ * `utils/errorClassifier.ts` (NetworkError classification) so both stay in
+ * sync — a second hand-maintained copy would drift the two apart the same
+ * way the "5xx literal text vs statusCode" split did.
+ *
+ * undici's native `fetch()` wraps the real transport failure in
+ * `TypeError: fetch failed`, with the actionable code on `error.cause`
+ * (sometimes nested another level deep, e.g. a SocketError inside a
+ * ConnectTimeoutError) — never on the outer TypeError itself.
+ */
+export const TRANSIENT_NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ECONNREFUSED",
+    "EPIPE",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);

package/dist/factories/providerDescriptors.js

@@ -26,6 +26,9 @@ export const PROVIDER_DESCRIPTORS = [
         timeouts: { generateMs: 45_000, streamMs: 120_000 },
         autoSelectPriority: 7,
         apiKeyFormatPattern: API_KEY_FORMATS.bedrock,
+        // Falls back to the AWS SDK's own default credential chain (shared
+        // profile, IAM role) when these env vars are absent — see field JSDoc.
+        credentialsResolvedExternally: true,
     },
     {
         name: AIProviderName.OPENAI,
@@ -89,12 +92,14 @@ export const PROVIDER_DESCRIPTORS = [
             // priority than GOOGLE_APPLICATION_CREDENTIALS by the real gating
             // logic (hasGoogleCredentials() in googleVertex/client.ts and
             // googleVertex/utils.ts) — corrected here vs. the plan snippet, which
-            // omitted it.
+            // omitted it. GOOGLE_AUTH_CLIENT_EMAIL and GOOGLE_AUTH_PRIVATE_KEY are
+            // nested together because hasGoogleCredentials() only accepts them as
+            // a pair — either alone is not valid auth, unlike the other flat
+            // entries here which are each independently sufficient.
             extraRequiredFallbacks: [
                 "GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK",
                 "GOOGLE_SERVICE_ACCOUNT_KEY",
-                "GOOGLE_AUTH_CLIENT_EMAIL",
-                "GOOGLE_AUTH_PRIVATE_KEY",
+                ["GOOGLE_AUTH_CLIENT_EMAIL", "GOOGLE_AUTH_PRIVATE_KEY"],
             ],
         },
         defaultModel: VertexModels.CLAUDE_4_6_SONNET,
@@ -104,6 +109,9 @@ export const PROVIDER_DESCRIPTORS = [
         setupUrl: "https://console.cloud.google.com/",
         timeouts: { generateMs: 60_000, streamMs: 120_000 },
         autoSelectPriority: 3,
+        // OR-of-multiple-auth-paths (file / individual fields / base64 key) —
+        // not a flat AND-list of required env vars. See field JSDoc.
+        credentialsResolvedExternally: true,
     },
     {
         name: AIProviderName.ANTHROPIC,
@@ -241,6 +249,8 @@ export const PROVIDER_DESCRIPTORS = [
         setupUrl: "https://docs.litellm.ai/docs/proxy/quick_start",
         timeouts: { generateMs: 300_000, streamMs: 120_000 },
         autoSelectPriority: 1,
+        // Documented zero-config local proxy — see field JSDoc.
+        credentialsResolvedExternally: true,
     },
     {
         name: AIProviderName.SAGEMAKER,

package/dist/lib/constants/networkErrorCodes.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Error codes that indicate a transient transport failure (dropped
+ * connection, socket reset, connect timeout) rather than a permanent
+ * misconfiguration. Shared between `proxy/proxyFetch.ts` (retry gating) and
+ * `utils/errorClassifier.ts` (NetworkError classification) so both stay in
+ * sync — a second hand-maintained copy would drift the two apart the same
+ * way the "5xx literal text vs statusCode" split did.
+ *
+ * undici's native `fetch()` wraps the real transport failure in
+ * `TypeError: fetch failed`, with the actionable code on `error.cause`
+ * (sometimes nested another level deep, e.g. a SocketError inside a
+ * ConnectTimeoutError) — never on the outer TypeError itself.
+ */
+export declare const TRANSIENT_NETWORK_CODES: ReadonlySet<string>;

package/dist/lib/constants/networkErrorCodes.js

@@ -0,0 +1,22 @@
+/**
+ * Error codes that indicate a transient transport failure (dropped
+ * connection, socket reset, connect timeout) rather than a permanent
+ * misconfiguration. Shared between `proxy/proxyFetch.ts` (retry gating) and
+ * `utils/errorClassifier.ts` (NetworkError classification) so both stay in
+ * sync — a second hand-maintained copy would drift the two apart the same
+ * way the "5xx literal text vs statusCode" split did.
+ *
+ * undici's native `fetch()` wraps the real transport failure in
+ * `TypeError: fetch failed`, with the actionable code on `error.cause`
+ * (sometimes nested another level deep, e.g. a SocketError inside a
+ * ConnectTimeoutError) — never on the outer TypeError itself.
+ */
+export const TRANSIENT_NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ECONNREFUSED",
+    "EPIPE",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+//# sourceMappingURL=networkErrorCodes.js.map

package/dist/lib/factories/providerDescriptors.js

@@ -26,6 +26,9 @@ export const PROVIDER_DESCRIPTORS = [
         timeouts: { generateMs: 45_000, streamMs: 120_000 },
         autoSelectPriority: 7,
         apiKeyFormatPattern: API_KEY_FORMATS.bedrock,
+        // Falls back to the AWS SDK's own default credential chain (shared
+        // profile, IAM role) when these env vars are absent — see field JSDoc.
+        credentialsResolvedExternally: true,
     },
     {
         name: AIProviderName.OPENAI,
@@ -89,12 +92,14 @@ export const PROVIDER_DESCRIPTORS = [
             // priority than GOOGLE_APPLICATION_CREDENTIALS by the real gating
             // logic (hasGoogleCredentials() in googleVertex/client.ts and
             // googleVertex/utils.ts) — corrected here vs. the plan snippet, which
-            // omitted it.
+            // omitted it. GOOGLE_AUTH_CLIENT_EMAIL and GOOGLE_AUTH_PRIVATE_KEY are
+            // nested together because hasGoogleCredentials() only accepts them as
+            // a pair — either alone is not valid auth, unlike the other flat
+            // entries here which are each independently sufficient.
             extraRequiredFallbacks: [
                 "GOOGLE_APPLICATION_CREDENTIALS_NEUROLINK",
                 "GOOGLE_SERVICE_ACCOUNT_KEY",
-                "GOOGLE_AUTH_CLIENT_EMAIL",
-                "GOOGLE_AUTH_PRIVATE_KEY",
+                ["GOOGLE_AUTH_CLIENT_EMAIL", "GOOGLE_AUTH_PRIVATE_KEY"],
             ],
         },
         defaultModel: VertexModels.CLAUDE_4_6_SONNET,
@@ -104,6 +109,9 @@ export const PROVIDER_DESCRIPTORS = [
         setupUrl: "https://console.cloud.google.com/",
         timeouts: { generateMs: 60_000, streamMs: 120_000 },
         autoSelectPriority: 3,
+        // OR-of-multiple-auth-paths (file / individual fields / base64 key) —
+        // not a flat AND-list of required env vars. See field JSDoc.
+        credentialsResolvedExternally: true,
     },
     {
         name: AIProviderName.ANTHROPIC,
@@ -241,6 +249,8 @@ export const PROVIDER_DESCRIPTORS = [
         setupUrl: "https://docs.litellm.ai/docs/proxy/quick_start",
         timeouts: { generateMs: 300_000, streamMs: 120_000 },
         autoSelectPriority: 1,
+        // Documented zero-config local proxy — see field JSDoc.
+        credentialsResolvedExternally: true,
     },
     {
         name: AIProviderName.SAGEMAKER,

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

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