@juspay/neurolink 12.47.2 → 12.47.4

package/dist/core/loopEngine.js

@@ -366,7 +366,7 @@ export function runAgenticLoop(adapter, initialConversation, options) {
                     // The caller's span, when it passes one. withProviderRetry writes
                     // gen_ai.provider.total_attempts here, so a loop that threaded a
                     // span before it moved onto this engine keeps emitting it.
-                    options.span, `${adapter.providerLabel}.step`);
+                    options.span, `${adapter.providerLabel}.step`, undefined, internalAbort.signal);
                 }
                 catch (err) {
                     throw err instanceof PostEmissionStepError ? err.cause : err;

package/dist/processors/media/VideoProcessor.js

@@ -445,7 +445,10 @@ export class VideoProcessor extends BaseFileProcessor {
                         metadata = this.buildMetadata(probeResult.data, buffer.length);
                     }
                 }
-                if (!metadata) {
+                // mediabunny reports a duration of 0 for a clip it can open but not
+                // time, and ffprobe's "N/A" parses to NaN: neither is a missing
+                // result, so both take the ffmpeg fallback.
+                if (!metadata || !(metadata.duration > 0)) {
                     // ffmpeg-static ships ffmpeg only, so a host that relies on it has
                     // no ffprobe. Without a duration no frame timestamps can be chosen.
                     const ffmpegProbe = await this.probeVideoWithFfmpeg(tempVideoPath);
@@ -456,7 +459,9 @@ export class VideoProcessor extends BaseFileProcessor {
                         // Nothing downstream reports this: an empty duration selects no
                         // frames, the request still succeeds, and the model is simply
                         // told nothing about the video.
-                        logger.warn(`[NEUROLINK] No metadata could be read for ${filename} (mediabunny, ffprobe and ffmpeg all failed), so no keyframes will be extracted: ${ffmpegProbe.error}`);
+                        logger.warn(metadata
+                            ? `[NEUROLINK] No positive duration could be read for ${filename} (the first reader gave none and ffmpeg could not supply one), so frame times cannot be chosen: ${ffmpegProbe.error}`
+                            : `[NEUROLINK] No metadata could be read for ${filename} (mediabunny, ffprobe and ffmpeg all failed), so no keyframes will be extracted: ${ffmpegProbe.error}`);
                     }
                 }
                 if (!metadata) {

package/dist/providers/amazonSagemaker.js

@@ -242,7 +242,7 @@ export class AmazonSageMakerProvider extends BaseProvider {
             ...(options.toolTimeoutMs !== undefined
                 ? { toolTimeoutMs: options.toolTimeoutMs }
                 : {}),
-            runStep: (call) => withProviderRetry(call, undefined, "sagemaker generate").catch((err) => {
+            runStep: (call) => withProviderRetry(call, undefined, "sagemaker generate", undefined, options.abortSignal).catch((err) => {
                 throw this.handleProviderError(err);
             }),
         }, toolExecutionSummaries);

package/dist/providers/anthropic/client.d.ts

@@ -11,6 +11,15 @@ export declare class AnthropicProvider extends BaseProvider {
     private readonly authMethod;
     private readonly subscriptionTier;
     private readonly enableBetaFeatures;
+    /**
+     * Where requests go when not to `api.anthropic.com`: the credentials'
+     * `baseURL`, else the config's, else `ANTHROPIC_BASE_URL` — normalized once
+     * (no trailing slash, no `/vN` suffix: the SDK appends `/v1` itself).
+     * Undefined means the vendor's own endpoint; every "proxy in use" decision
+     * reads this, never the environment directly, so a per-instance gateway is
+     * honoured the same way the environment one always was.
+     */
+    private readonly baseURL;
     private oauthToken;
     private lastResponseMetadata;
     private usageInfo;
@@ -25,6 +34,7 @@ export declare class AnthropicProvider extends BaseProvider {
     constructor(modelName?: string, sdk?: unknown, config?: AnthropicProviderConfig, credentials?: {
         apiKey?: string;
         oauthToken?: string;
+        baseURL?: string;
     });
     /**
      * Get authentication headers based on current auth method and configuration.

package/dist/providers/anthropic/client.js

@@ -58,6 +58,31 @@ const getAnthropicApiKey = () => {
 const getDefaultAnthropicModel = () => {
     return getProviderModel("ANTHROPIC_MODEL", AnthropicModels.CLAUDE_SONNET_4_6);
 };
+/**
+ * The official Anthropic SDK builds `${baseURL}/v1/messages` itself, so a
+ * version-suffixed base URL — the form the previous @ai-sdk/anthropic
+ * implementation REQUIRED (`https://api.anthropic.com/v1`) — would double up
+ * as `/v1/v1/messages`. Normalize the inverse way: strip trailing slashes and
+ * a trailing `/vN` segment, so both historical forms keep working whether the
+ * URL comes from the credentials, the config or `ANTHROPIC_BASE_URL`. Blank
+ * means "the vendor's endpoint".
+ */
+function normalizeAnthropicBaseURL(raw) {
+    const value = raw?.trim();
+    if (!value) {
+        return undefined;
+    }
+    const trimmed = value.replace(/\/+$/, "");
+    const stripped = trimmed.replace(/\/v\d+$/, "");
+    if (stripped !== trimmed) {
+        logger.debug("[AnthropicProvider] Stripping the version suffix from the base URL — " +
+            "the official Anthropic SDK appends /v1 to the base URL itself.", {
+            baseURL: redactUrlCredentials(value),
+            rewrittenTo: redactUrlCredentials(stripped),
+        });
+    }
+    return stripped;
+}
 const streamTracer = trace.getTracer("neurolink.provider.anthropic");
 /**
  * Get OAuth token from stored credentials file or environment.
@@ -476,6 +501,15 @@ export class AnthropicProvider extends BaseProvider {
     authMethod;
     subscriptionTier;
     enableBetaFeatures;
+    /**
+     * Where requests go when not to `api.anthropic.com`: the credentials'
+     * `baseURL`, else the config's, else `ANTHROPIC_BASE_URL` — normalized once
+     * (no trailing slash, no `/vN` suffix: the SDK appends `/v1` itself).
+     * Undefined means the vendor's own endpoint; every "proxy in use" decision
+     * reads this, never the environment directly, so a per-instance gateway is
+     * honoured the same way the environment one always was.
+     */
+    baseURL;
     oauthToken;
     lastResponseMetadata = null;
     usageInfo = null;
@@ -511,12 +545,16 @@ export class AnthropicProvider extends BaseProvider {
         const subscriptionTier = config?.subscriptionTier ??
             (authMethod === "oauth" ? detectSubscriptionTier(oauthToken) : "api");
         const targetModel = modelName || getDefaultAnthropicModel();
+        // Resolved before super(): the tier check below needs it, and the
+        // credentials win over the config, which wins over the environment —
+        // the same precedence `apiKey` has.
+        const baseURL = normalizeAnthropicBaseURL(credentials?.baseURL ?? config?.baseURL ?? process.env.ANTHROPIC_BASE_URL);
         // Determine effective model based on tier access.
-        // Skip tier validation when a proxy is in use (ANTHROPIC_BASE_URL is set)
-        // — the proxy handles model access and auth, so the SDK should pass
-        // the requested model through without downgrading.
+        // Skip tier validation when a proxy is in use (a base URL is set) — the
+        // proxy handles model access and auth, so the SDK should pass the
+        // requested model through without downgrading.
         let effectiveModel = targetModel;
-        const usingProxy = !!process.env.ANTHROPIC_BASE_URL;
+        const usingProxy = baseURL !== undefined;
         if (!usingProxy &&
             subscriptionTier !== "api" &&
             !isModelAvailableForTier(targetModel, subscriptionTier)) {
@@ -533,6 +571,7 @@ export class AnthropicProvider extends BaseProvider {
         // Store computed values
         this.oauthToken = oauthToken;
         this.subscriptionTier = subscriptionTier;
+        this.baseURL = baseURL;
         // Use the auth method already resolved above (before tier computation)
         this.authMethod = authMethod;
         // Build headers based on auth method and subscription tier
@@ -570,6 +609,9 @@ export class AnthropicProvider extends BaseProvider {
             // The claude-code-20250219 beta header triggers "credential only for Claude Code" error
             client = new Anthropic({
                 apiKey: "oauth-authenticated", // Placeholder, actual auth is in fetch wrapper
+                // The same gateway the API-key branch honours: without it, OAuth
+                // credentials that also name a base URL would still reach the vendor.
+                ...(this.baseURL && { baseURL: this.baseURL }),
                 // Note: No headers passed - fetch wrapper sets oauth-2025-04-20 beta header
                 // Limit capture wraps the OAuth fetch so subscription quota headers
                 // (anthropic-ratelimit-unified-*) are recorded on every request —
@@ -599,33 +641,10 @@ export class AnthropicProvider extends BaseProvider {
         else {
             // Traditional API key authentication
             const apiKeyToUse = credentials?.apiKey ?? config?.apiKey ?? getAnthropicApiKey();
-            // The official Anthropic SDK builds `${baseURL}/v1/messages` itself, so
-            // a version-suffixed base URL — the form the previous @ai-sdk/anthropic
-            // implementation REQUIRED (`https://api.anthropic.com/v1`) — would
-            // double up as `/v1/v1/messages`. Normalize the inverse way now: strip
-            // a trailing `/vN` segment when present so both historical forms of
-            // ANTHROPIC_BASE_URL keep working.
-            const normalizedBaseURL = (() => {
-                const raw = process.env.ANTHROPIC_BASE_URL;
-                if (!raw) {
-                    return undefined;
-                }
-                const trimmed = raw.replace(/\/+$/, "");
-                const stripped = trimmed.replace(/\/v\d+$/, "");
-                if (stripped !== trimmed) {
-                    logger.debug("[AnthropicProvider] Stripping the version suffix from " +
-                        "ANTHROPIC_BASE_URL — the official Anthropic SDK appends /v1 " +
-                        "to the base URL itself.", {
-                        baseURL: redactUrlCredentials(raw),
-                        rewrittenTo: redactUrlCredentials(stripped),
-                    });
-                }
-                return stripped;
-            })();
             client = new Anthropic({
                 apiKey: apiKeyToUse,
                 defaultHeaders: headers,
-                ...(normalizedBaseURL && { baseURL: normalizedBaseURL }),
+                ...(this.baseURL && { baseURL: this.baseURL }),
                 // Same capture as the OAuth branch: works for direct API-key traffic
                 // (legacy requests/tokens counters) and for the NeuroLink Claude proxy
                 // (verbatim unified quota plus x-neurolink-* account/pool state).
@@ -676,10 +695,11 @@ export class AnthropicProvider extends BaseProvider {
      */
     getAuthHeaders() {
         const headers = {};
-        // When routing through proxy (ANTHROPIC_BASE_URL set), use the full
-        // OAuth beta set so the proxy forwards them upstream. Without these,
-        // Anthropic treats the request with tighter non-subscription rate limits.
-        const usingProxy = !!process.env.ANTHROPIC_BASE_URL;
+        // When routing through a proxy (a base URL is set — per instance or
+        // ANTHROPIC_BASE_URL), use the full OAuth beta set so the proxy forwards
+        // them upstream. Without these, Anthropic treats the request with tighter
+        // non-subscription rate limits.
+        const usingProxy = this.baseURL !== undefined;
         if (this.enableBetaFeatures) {
             if (usingProxy) {
                 // The 1M-context beta requires a plan upgrade on most accounts;
@@ -705,9 +725,9 @@ export class AnthropicProvider extends BaseProvider {
             }
         }
         if (usingProxy) {
-            // WAFs in front of ANTHROPIC_BASE_URL proxies commonly block the bare
-            // SDK UA ("Anthropic/JS x.y.z"); send the claude-cli UA the OAuth path
-            // already uses. Direct-to-Anthropic traffic keeps the honest SDK UA.
+            // WAFs in front of Anthropic proxies commonly block the bare SDK UA
+            // ("Anthropic/JS x.y.z"); send the claude-cli UA the OAuth path already
+            // uses. Direct-to-Anthropic traffic keeps the honest SDK UA.
             headers["User-Agent"] = CLAUDE_CLI_USER_AGENT;
         }
         // Add subscription-specific headers if applicable
@@ -736,8 +756,8 @@ export class AnthropicProvider extends BaseProvider {
         // Proxy mode: bypass tier validation entirely — the proxy handles model
         // access. Log at debug level so users can tell why an unknown model name
         // "validated" when their proxy may not actually expose it.
-        if (process.env.ANTHROPIC_BASE_URL) {
-            logger.debug("[validateModelAccess] Bypassing tier check (ANTHROPIC_BASE_URL set — proxy enforces access)", { model });
+        if (this.baseURL !== undefined) {
+            logger.debug("[validateModelAccess] Bypassing tier check (a base URL is set — the proxy enforces access)", { model });
             return true;
         }
         // API tier has access to all models
@@ -1603,7 +1623,7 @@ export class AnthropicProvider extends BaseProvider {
             ...(options.toolTimeoutMs !== undefined
                 ? { toolTimeoutMs: options.toolTimeoutMs }
                 : {}),
-            runStep: (call) => withProviderRetry(call, trace.getActiveSpan() ?? undefined, "anthropic generate").catch((err) => {
+            runStep: (call) => withProviderRetry(call, trace.getActiveSpan() ?? undefined, "anthropic generate", undefined, options.abortSignal).catch((err) => {
                 throw this.handleProviderError(err);
             }),
         }, toolExecutionSummaries);

package/dist/providers/nvidiaNim/client.js

@@ -270,7 +270,9 @@ export class NvidiaNimProvider extends OpenAIChatCompletionsProvider {
                 message: "NVIDIA NIM rate limit exceeded",
             },
             {
-                match: (ctx) => /404|model_not_found/.test(ctx.message),
+                // NIM answers most of its roster with a 404 whose text ("Function …
+                // not found for account …") names no model, so the status decides.
+                match: (ctx) => ctx.statusCode === 404 || /404|model_not_found/.test(ctx.message),
                 errorClass: InvalidModelError,
                 message: () => `NVIDIA NIM model '${this.modelName}' not available. Browse the catalog at https://build.nvidia.com/models`,
             },

package/dist/providers/openaiChatCompletionsBase.js

@@ -989,7 +989,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                 // supplied around each call: without them a 429 surfaces as a raw
                 // upstream string instead of a RateLimitError, and a throttle is
                 // never retried.
-                runStep: (call) => withProviderRetry(call, trace.getActiveSpan() ?? undefined, `${this.providerName} generate`).catch((err) => {
+                runStep: (call) => withProviderRetry(call, trace.getActiveSpan() ?? undefined, `${this.providerName} generate`, undefined, options.abortSignal).catch((err) => {
                     throw this.handleProviderError(err);
                 }),
             }, toolExecutionSummaries);
@@ -2188,7 +2188,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         };
         let res;
         try {
-            res = await withProviderRetry(doFetch, trace.getActiveSpan() ?? undefined, `${this.providerName} stream`);
+            res = await withProviderRetry(doFetch, trace.getActiveSpan() ?? undefined, `${this.providerName} stream`, undefined, args.abortSignal);
         }
         catch (err) {
             // The one-shot 400 context-overflow fallback lives outside

package/dist/types/model.d.ts

@@ -272,9 +272,9 @@ export type ModelRoutingOptions = {
 /**
  * A single model's metadata inside a provider's manifest. This is the one
  * canonical shape every model-metadata consumer (context windows, pricing,
- * MODEL_REGISTRY, vision capability, output-token ceilings) is intended to
- * migrate onto — this PR is purely additive and does not yet move any
- * consumer over.
+ * MODEL_REGISTRY, vision capability, output-token ceilings) reads from —
+ * contextWindows.ts, pricing.ts, modelRegistry.ts, providerImageAdapter.ts and
+ * core/constants.ts.
  *
  * `pricingPerMTok` is optional by design: a model with no verified price
  * (e.g. a just-announced model pricing.ts hasn't priced yet) must not report
@@ -311,9 +311,10 @@ export type ProviderModelManifestEntry = {
      * forward verbatim for the ids that already had a MODEL_REGISTRY entry
      * before this migration. Absent for every id that never had one — those
      * get performance/useCases/category derived mechanically instead (see
-     * Task 9's buildModelRegistryFromManifests). Never populate this for a
-     * genuinely new model: mechanical derivation is the correct default, and
-     * a fabricated "curated" value would be worse than an honestly-derived one.
+     * buildManifestDerivedEntries in src/lib/models/modelRegistry.ts). Never
+     * populate this for a genuinely new model: mechanical derivation is the
+     * correct default, and a fabricated "curated" value would be worse than an
+     * honestly-derived one.
      */
     curated?: {
         performance?: ModelPerformance;

package/dist/types/providers.d.ts

@@ -105,9 +105,16 @@ export type NeurolinkCredentials = {
         apiKey?: string;
         baseURL?: string;
     };
+    /**
+     * Anthropic. `baseURL` points the official SDK client at a gateway or proxy
+     * instead of `api.anthropic.com` (with or without a trailing `/v1`); it
+     * takes precedence over `ANTHROPIC_BASE_URL`, exactly as `apiKey` does over
+     * `ANTHROPIC_API_KEY`.
+     */
     anthropic?: {
         apiKey?: string;
         oauthToken?: string;
+        baseURL?: string;
     };
     googleAiStudio?: {
         apiKey?: string;
@@ -2401,7 +2408,14 @@ export type ProviderDescriptor = {
      * checks to its own server (TypeSafe). See {@link DecisionLimits}.
      */
     decisionLimits?: DecisionLimits;
-    /** Ascending priority (1 = tried first) in the auto-select fallback chain used by getBestProvider(). Undefined = not part of the auto-select chain. */
+    /**
+     * Ascending priority (1 = tried first) in the auto-select fallback chain
+     * used by getBestProvider(). Undefined = not part of the auto-select chain.
+     *
+     * Priorities favor local and self-hosted deployments first to avoid an
+     * external dependency during fallback, then cloud providers according to
+     * reliability, feature set and model coverage.
+     */
     autoSelectPriority?: number;
     /** Format-validation regex sourced from providerConfig.ts's API_KEY_FORMATS, when one exists for this provider. */
     apiKeyFormatPattern?: RegExp;

package/dist/utils/errorClassifier.d.ts

@@ -21,10 +21,13 @@ export declare function classifyProviderError(error: unknown, rules: ProviderErr
 /**
  * Generic fallback rule table covering the five categories every
  * OpenAI-compatible provider already hand-rolled near-identically:
- * auth (401), rate limit (429), model-not-found (404), network/connection
- * errors, and 5xx server errors. Providers with a provider-specific auth
- * message (naming the exact env var) prepend one override rule and spread
- * this table after it — see errorClassifier usage in any migrated
+ * auth (401), rate limit (429), model-not-found, network/connection
+ * errors, and 5xx server errors. Model-not-found is a 404 whose text names
+ * the model or deployment as missing, or the old "model not found" message
+ * text at any status; any other 404 stays a plain `ProviderError` carrying
+ * the status and the vendor's message. Providers with a provider-specific
+ * auth message (naming the exact env var) prepend one override rule and
+ * spread this table after it — see errorClassifier usage in any migrated
  * provider's formatProviderError for the pattern.
  */
 export declare const DEFAULT_ERROR_RULES: ProviderErrorRule[];

package/dist/utils/errorClassifier.js

@@ -113,13 +113,20 @@ export function classifyProviderError(error, rules, provider, modelName) {
     const message = typeof rule.message === "function" ? rule.message(ctx) : rule.message;
     return new rule.errorClass(message, provider);
 }
+// A 404 alone is a route answer (a wrong base URL gives the same reply): it only
+// means "missing model" when the text names a model or deployment as absent.
+// The gap is bounded rather than "no dot" because real model ids contain dots.
+const MODEL_404_TEXT = /model[_ ]?not[_ ]?found|unknown model|no such model|invalid model|unsupported model|\b(?:model|deployment)\b.{0,120}\b(?:does not exist|not found|unavailable|not (?:available|supported))\b|\b(?:does not exist|not found)\b.{0,120}\b(?:model|deployment)\b|unable to access.{0,60}\bmodel\b/i;
 /**
  * Generic fallback rule table covering the five categories every
  * OpenAI-compatible provider already hand-rolled near-identically:
- * auth (401), rate limit (429), model-not-found (404), network/connection
- * errors, and 5xx server errors. Providers with a provider-specific auth
- * message (naming the exact env var) prepend one override rule and spread
- * this table after it — see errorClassifier usage in any migrated
+ * auth (401), rate limit (429), model-not-found, network/connection
+ * errors, and 5xx server errors. Model-not-found is a 404 whose text names
+ * the model or deployment as missing, or the old "model not found" message
+ * text at any status; any other 404 stays a plain `ProviderError` carrying
+ * the status and the vendor's message. Providers with a provider-specific
+ * auth message (naming the exact env var) prepend one override rule and
+ * spread this table after it — see errorClassifier usage in any migrated
  * provider's formatProviderError for the pattern.
  */
 export const DEFAULT_ERROR_RULES = [
@@ -135,13 +142,18 @@ export const DEFAULT_ERROR_RULES = [
         message: (ctx) => `${ctx.provider} rate limit exceeded. Please try again later.`,
     },
     {
-        match: (ctx) => ctx.statusCode === 404 ||
-            /model_not_found|model not found/i.test(ctx.message),
+        match: (ctx) => /model_not_found|model not found/i.test(ctx.message) ||
+            (ctx.statusCode === 404 && MODEL_404_TEXT.test(ctx.message)),
         errorClass: InvalidModelError,
         message: (ctx) => ctx.modelName
             ? `${ctx.provider} model '${ctx.modelName}' not found.`
             : `${ctx.provider} model not found.`,
     },
+    {
+        match: (ctx) => ctx.statusCode === 404,
+        errorClass: ProviderError,
+        message: (ctx) => `${ctx.provider} returned HTTP 404: ${ctx.message}`,
+    },
     {
         // Message regex covers providers/SDKs that surface a code as text
         // (e.g. AWS SDK wrapping "ECONNRESET" into its own message). errorCode

package/dist/utils/messageBuilder.js

@@ -2566,7 +2566,14 @@ mediaOptions = {}) {
                 });
                 try {
                     const extracted = await parser.getText();
-                    const pdfText = (extracted?.text ?? "").trim();
+                    // pdf-parse appends a "-- n of N --" marker after every page, so
+                    // extracted.text is never empty; a scan is detected from the
+                    // per-page text instead.
+                    const pageTexts = extracted?.pages?.map((page) => page.text) ?? [
+                        extracted?.text ?? "",
+                    ];
+                    const hasTextLayer = pageTexts.some((text) => text.trim().length > 0);
+                    const pdfText = hasTextLayer ? (extracted?.text ?? "").trim() : "";
                     if (pdfText.length > 0) {
                         content.push({
                             type: "text",
@@ -2574,6 +2581,13 @@ mediaOptions = {}) {
                         });
                         logger.info(`[PDF→Text] ✅ Extracted text for non-vision provider ${provider}: ${name} (${pdfText.length} chars)`);
                     }
+                    else if (providerCanSeeImages) {
+                        content.push({
+                            type: "text",
+                            text: `\n[Attached PDF: ${name} — no extractable text layer (likely a scanned document); page images are attached below.]`,
+                        });
+                        logger.warn(`[PDF→Text] ${name} has no text layer; page images follow`);
+                    }
                     else {
                         content.push({
                             type: "text",

package/dist/utils/modelChoices.d.ts

@@ -15,6 +15,13 @@ import type { CatalogProviderName, ModelChoice } from "../types/index.js";
  *
  * AUTO is also excluded — it never had an entry here either (matches
  * pre-existing behavior: `getDefaultModel(AUTO)` returns `undefined`).
+ *
+ * This table is not what a call with no model uses. The runtime order is the
+ * explicit model, then the provider's environment variable, then the default in
+ * the dynamic model configuration, then the registry default
+ * (`providerRegistry.ts`); the OpenAI row mirrors that registry default. Only
+ * an `OpenAIProvider` constructed directly with none of those falls back to
+ * `gpt-5.4` (`openAI/client.ts`).
  */
 export declare const DEFAULT_MODELS: Record<Exclude<AIProviderName, CatalogProviderName | AIProviderName.AUTO>, string>;
 /**
@@ -56,6 +63,9 @@ export declare function getAllProviderChoices(): string[];
 /**
  * Get the default model for a provider
  *
+ * Reads `DEFAULT_MODELS`, which mirrors the registry default rather than the
+ * runtime resolution order (see the note on that table).
+ *
  * @param provider - The AI provider
  * @returns Default model string for the provider
  */

package/dist/utils/modelChoices.js

@@ -43,14 +43,19 @@ function catalogTopModels(entry) {
  */
 const TOP_MODELS_CONFIG = {
     [AIProviderName.OPENAI]: [
+        {
+            model: OpenAIModels.GPT_5_4,
+            description: "Recommended - Direct OpenAI GPT-5.4 model",
+        },
+        { model: OpenAIModels.GPT_5_4_MINI, description: "Cost-effective, fast" },
         {
             model: OpenAIModels.GPT_4O,
-            description: "Recommended - Latest multimodal model",
+            description: "Previous generation multimodal model",
         },
         { model: OpenAIModels.GPT_4O_MINI, description: "Cost-effective, fast" },
         {
             model: OpenAIModels.GPT_5_2,
-            description: "Latest flagship with deep reasoning",
+            description: "Previous flagship with deep reasoning",
         },
         { model: OpenAIModels.O3, description: "Advanced reasoning model" },
         { model: OpenAIModels.GPT_4_TURBO, description: "Previous generation" },
@@ -422,9 +427,16 @@ const TOP_MODELS_CONFIG = {
  *
  * AUTO is also excluded — it never had an entry here either (matches
  * pre-existing behavior: `getDefaultModel(AUTO)` returns `undefined`).
+ *
+ * This table is not what a call with no model uses. The runtime order is the
+ * explicit model, then the provider's environment variable, then the default in
+ * the dynamic model configuration, then the registry default
+ * (`providerRegistry.ts`); the OpenAI row mirrors that registry default. Only
+ * an `OpenAIProvider` constructed directly with none of those falls back to
+ * `gpt-5.4` (`openAI/client.ts`).
  */
 export const DEFAULT_MODELS = {
-    [AIProviderName.OPENAI]: OpenAIModels.GPT_4O,
+    [AIProviderName.OPENAI]: OpenAIModels.GPT_4O_MINI,
     [AIProviderName.ANTHROPIC]: AnthropicModels.CLAUDE_SONNET_4_5,
     [AIProviderName.GOOGLE_AI]: GoogleAIModels.GEMINI_2_5_FLASH,
     [AIProviderName.VERTEX]: VertexModels.GEMINI_2_5_FLASH,
@@ -572,6 +584,9 @@ export function getAllProviderChoices() {
 /**
  * Get the default model for a provider
  *
+ * Reads `DEFAULT_MODELS`, which mirrors the registry default rather than the
+ * runtime resolution order (see the note on that table).
+ *
  * @param provider - The AI provider
  * @returns Default model string for the provider
  */

package/dist/utils/providerHealth.js

@@ -305,10 +305,17 @@ export class ProviderHealthChecker {
             }
             return;
         }
+        // A descriptor with no apiKey variable at all (LM Studio, llama.cpp) would
+        // otherwise read process.env[""] below and report a missing key named by
+        // nothing; hasProviderEnvVars already treats these as usable with defaults.
+        const providerDescriptor = ProviderFactory.getDescriptor(providerName);
         // Providers that don't use API keys directly
         if (providerName === AIProviderName.OLLAMA ||
             providerName === AIProviderName.BEDROCK ||
-            providerName === AIProviderName.LITELLM) {
+            providerName === AIProviderName.LITELLM ||
+            providerDescriptor?.localRuntime === true ||
+            (providerDescriptor?.envVars.optional === true &&
+                !providerDescriptor.envVars.apiKey)) {
             healthStatus.hasApiKey = true;
             return;
         }
@@ -996,8 +1003,10 @@ export class ProviderHealthChecker {
                 ];
             case AIProviderName.OPENAI:
                 return [
-                    OpenAIModels.GPT_4O,
+                    OpenAIModels.GPT_5_4,
+                    OpenAIModels.GPT_5_4_MINI,
                     OpenAIModels.GPT_4O_MINI,
+                    OpenAIModels.GPT_4O,
                     OpenAIModels.GPT_3_5_TURBO,
                 ];
             case AIProviderName.GOOGLE_AI:
@@ -1541,8 +1550,18 @@ export class ProviderHealthChecker {
                 return provider;
             }
         }
-        // Fallback to first healthy provider
-        const firstHealthyProvider = healthStatuses.find((h) => h.isHealthy);
+        // Fallback to first healthy provider. A local runtime that nothing probes
+        // (LM Studio, llama.cpp) is "healthy" only in that it needs no
+        // configuration, which says nothing about whether it is running, so it
+        // must not outrank a provider the caller actually configured.
+        const firstHealthyProvider = healthStatuses.find((h) => {
+            if (!h.isHealthy) {
+                return false;
+            }
+            const descriptor = ProviderFactory.getDescriptor(h.provider);
+            return !(descriptor?.localRuntime === true &&
+                descriptor.healthCheck === "env-only");
+        });
         if (firstHealthyProvider) {
             logger.info(`Using fallback healthy provider: ${firstHealthyProvider.provider}`);
             return firstHealthyProvider.provider;

package/dist/utils/providerRetry.d.ts

@@ -86,6 +86,10 @@ export declare function getErrorStatusCode(error: unknown): number | undefined;
  * @param operation  - The async operation to execute (should already use `maxRetries: 0`)
  * @param span       - The OTel span to annotate with retry events and attributes
  * @param label      - A human-readable label for log messages (e.g. "generateText", "streamText")
+ * @param sleep      - Wait between attempts; receives the delay and the caller's abort signal
+ * @param abortSignal - The caller's cancellation. An abort during the wait ends the call with the
+ *                     signal's reason instead of waiting out the delay and running the operation
+ *                     again, and an already-aborted signal is checked before every attempt.
  * @returns The result of the operation
  */
-export declare function withProviderRetry<T>(operation: () => Promise<T>, span: Span | undefined, label: string, sleep?: (delayMs: number) => Promise<void>): Promise<T>;
+export declare function withProviderRetry<T>(operation: () => Promise<T>, span: Span | undefined, label: string, sleep?: (delayMs: number, abortSignal?: AbortSignal) => Promise<void>, abortSignal?: AbortSignal): Promise<T>;

package/dist/utils/providerRetry.js

@@ -33,7 +33,21 @@ export const NO_HINT_FLOOR_MS = 10_000;
  * get a prompt rate-limit error rather than a silent multi-minute stall.
  */
 export const MAX_RETRY_AFTER_MS = 60_000;
-const sleepWithTimeout = (delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs));
+const sleepWithTimeout = (delayMs, abortSignal) => new Promise((resolve, reject) => {
+    if (abortSignal?.aborted) {
+        reject(abortSignal.reason);
+        return;
+    }
+    const onAbort = () => {
+        clearTimeout(timer);
+        reject(abortSignal?.reason);
+    };
+    const timer = setTimeout(() => {
+        abortSignal?.removeEventListener("abort", onAbort);
+        resolve();
+    }, delayMs);
+    abortSignal?.addEventListener("abort", onAbort, { once: true });
+});
 /**
  * Check whether an error thrown by the AI SDK is retryable.
  *
@@ -244,10 +258,15 @@ function getRetryAfterMs(error) {
  * @param operation  - The async operation to execute (should already use `maxRetries: 0`)
  * @param span       - The OTel span to annotate with retry events and attributes
  * @param label      - A human-readable label for log messages (e.g. "generateText", "streamText")
+ * @param sleep      - Wait between attempts; receives the delay and the caller's abort signal
+ * @param abortSignal - The caller's cancellation. An abort during the wait ends the call with the
+ *                     signal's reason instead of waiting out the delay and running the operation
+ *                     again, and an already-aborted signal is checked before every attempt.
  * @returns The result of the operation
  */
-export async function withProviderRetry(operation, span, label, sleep = sleepWithTimeout) {
+export async function withProviderRetry(operation, span, label, sleep = sleepWithTimeout, abortSignal) {
     for (let attempt = 0; attempt <= MAX_PROVIDER_RETRIES; attempt++) {
+        abortSignal?.throwIfAborted();
         try {
             const result = await operation();
             // Record how many attempts it took on the span
@@ -314,7 +333,10 @@ export async function withProviderRetry(operation, span, label, sleep = sleepWit
                 statusCode,
                 error: errorMessage,
             });
-            await sleep(delay);
+            await sleep(delay, abortSignal);
+            // A custom sleep may ignore the signal, and a signal can abort in the
+            // same tick the timer fires.
+            abortSignal?.throwIfAborted();
         }
     }
     // This should never be reached due to the throw inside the loop,

package/dist/utils/providerUtils.js

@@ -52,16 +52,8 @@ export async function getBestProvider(requestedProvider) {
             // Fall through to cloud providers
         }
     }
-    /**
-     * Provider priority order rationale:
-     * - LiteLLM and Ollama are prioritized first for local/self-hosted deployments,
-     *   avoiding unnecessary dependence on external providers during fallback scenarios.
-     * - Vertex (Google Cloud AI) follows for enterprise-grade reliability.
-     * - Google AI follows as second cloud priority for comprehensive Google AI ecosystem support.
-     * - OpenAI maintains high priority due to its consistent reliability and broad model support.
-     * - Other providers are ordered based on a combination of reliability, feature set, and historical performance.
-     * Please update this comment if the order is changed in the future, and document the rationale for maintainability.
-     */
+    // Order comes from ProviderDescriptor.autoSelectPriority (lower = tried
+    // first); see providerDescriptors.ts and the catalog JSON.
     const providers = PROVIDER_DESCRIPTORS.filter((d) => d.autoSelectPriority !== undefined)
         .sort((a, b) => (a.autoSelectPriority ?? 0) - (b.autoSelectPriority ?? 0))
         .map((d) => d.name);