@juspay/neurolink 12.23.2 → 12.24.0

package/dist/providers/catalog/loader.js

@@ -41,11 +41,12 @@ export function catalogEnvVar(entry, kind) {
             ? `${base}_BASE_URL`
             : `${base}_MODEL`;
 }
-function interpolate(template, entry, modelName) {
+function interpolate(template, entry, modelName, rawMessage) {
     return template
         .replace(/\{apiKeyEnvVar\}/g, catalogEnvVar(entry, "apiKey"))
         .replace(/\{setupUrl\}/g, entry.setup.url)
-        .replace(/\{model\}/g, modelName ?? "");
+        .replace(/\{model\}/g, modelName ?? "")
+        .replace(/\{message\}/g, rawMessage ?? "");
 }
 export function buildCatalogConfigOptions(entry) {
     return {
@@ -54,17 +55,21 @@ export function buildCatalogConfigOptions(entry) {
         setupUrl: entry.setup.url,
         description: entry.setup.description ?? "API key",
         instructions: entry.setup.instructions.map((line) => interpolate(line, entry)),
+        ...(entry.wire.apiKeyFallbackEnvVars
+            ? { fallbackEnvVars: entry.wire.apiKeyFallbackEnvVars }
+            : {}),
     };
 }
 function buildErrorRules(entry) {
     const bespoke = entry.errorRules.map((rule) => {
         const regex = rule.pattern ? new RegExp(rule.pattern, "i") : undefined;
+        const needsContext = rule.message.includes("{model}") || rule.message.includes("{message}");
         return {
             match: (ctx) => (rule.status !== undefined && ctx.statusCode === rule.status) ||
                 (regex !== undefined && regex.test(ctx.message)),
             errorClass: ERROR_CLASS_MAP[rule.class],
-            message: rule.message.includes("{model}")
-                ? (ctx) => interpolate(rule.message, entry, ctx.modelName)
+            message: needsContext
+                ? (ctx) => interpolate(rule.message, entry, ctx.modelName, ctx.message)
                 : interpolate(rule.message, entry),
         };
     });
@@ -118,7 +123,14 @@ export function buildCatalogEntries() {
                 entry.models.fallbacks[0],
             fallbackModels: [...entry.models.fallbacks],
             errorRules: buildErrorRules(entry),
-            supportsTools: entry.capabilities.tools,
+            // "model-dependent" leaves this field unset entirely (not the string
+            // itself, which OpenAICompatCatalogEntry.supportsTools types as
+            // boolean|undefined) so ConfiguredOpenAICompatProvider.supportsTools()
+            // falls through to the model-registry default, same as an entry that
+            // never set this field at all.
+            ...(typeof entry.capabilities.tools === "boolean"
+                ? { supportsTools: entry.capabilities.tools }
+                : {}),
         };
         const { baseURLTemplate } = entry.wire;
         if (baseURLTemplate) {
@@ -143,6 +155,9 @@ export function buildCatalogEntries() {
         if (entry.quirks?.timeoutErrorClass === "provider") {
             base.timeoutErrorClass = ProviderError;
         }
+        if (entry.quirks?.responseFormatDowngrade) {
+            base.responseFormatDowngrade = entry.quirks.responseFormatDowngrade;
+        }
         return base;
     });
 }

package/dist/providers/catalog/mistral.json

@@ -223,12 +223,17 @@
     "quirks": {
         "registryDefaultIgnoresModelEnvVar": true
     },
+    "timeouts": {
+        "generateMs": 45000,
+        "streamMs": 120000
+    },
+    "autoSelectPriority": 9,
     "setup": {
-        "url": "https://console.mistral.ai/",
-        "apiKeyFormat": null,
+        "url": "https://console.mistral.ai/api-keys",
+        "apiKeyFormat": "^[A-Za-z0-9]{32}$",
         "billingPolicy": "free-with-card",
         "instructions": [
-            "1. Visit: https://console.mistral.ai/",
+            "1. Visit: https://console.mistral.ai/api-keys",
             "2. Create or sign in to your account",
             "3. Generate a new API key"
         ]

package/dist/providers/catalog/provider-catalog.schema.json

@@ -67,6 +67,13 @@
         "missingCredentialMessage": {
           "type": "string"
         },
+        "apiKeyFallbackEnvVars": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Additional env vars validateApiKey() tries, in order, when the primary apiKeyEnvVar is unset (e.g. HF_TOKEN alongside HUGGINGFACE_API_KEY)."
+        },
         "envOverrides": {
           "type": "object",
           "additionalProperties": false,
@@ -205,7 +212,8 @@
           "type": "boolean"
         },
         "tools": {
-          "type": "boolean"
+          "anyOf": [{ "type": "boolean" }, { "const": "model-dependent" }],
+          "description": "\"model-dependent\" when tool support varies per served model and the vendor doesn't reject tools for unsupported ones (e.g. HuggingFace's router)."
         },
         "toolsWithStreaming": {
           "type": "boolean"
@@ -267,9 +275,31 @@
           "type": "string",
           "enum": ["string"],
           "description": "Vendor accepts messages[].content only as a plain string, rejecting OpenAI's content-parts array and the null used on an assistant message with tool_calls. Normalized by ConfiguredOpenAICompatProvider."
+        },
+        "responseFormatDowngrade": {
+          "type": "string",
+          "enum": ["json-schema-to-json-object"],
+          "description": "Vendor rejects response_format: { type: \"json_schema\" } outright but accepts { type: \"json_object\" }. ConfiguredOpenAICompatProvider downgrades the request so generate({ schema }) keeps working."
+        }
+      }
+    },
+    "timeouts": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Descriptor-only generate/stream turn-budget override consumed by buildCatalogDescriptor(); never read by the OpenAI-compat runtime path.",
+      "properties": {
+        "generateMs": {
+          "type": "number"
+        },
+        "streamMs": {
+          "type": "number"
         }
       }
     },
+    "autoSelectPriority": {
+      "type": "number",
+      "description": "Descriptor-only ascending auto-select priority override (lower = tried first in getBestProvider()'s fallback chain). Absent = provider is not part of the auto-select chain."
+    },
     "setup": {
       "type": "object",
       "additionalProperties": false,

package/dist/providers/catalog/schema.d.ts

@@ -23,6 +23,7 @@ export declare const providerCatalogJsonSchema: z.ZodObject<{
         baseURLTemplate: z.ZodOptional<z.ZodString>;
         extraCredentials: z.ZodOptional<z.ZodArray<z.ZodString>>;
         missingCredentialMessage: z.ZodOptional<z.ZodString>;
+        apiKeyFallbackEnvVars: z.ZodOptional<z.ZodArray<z.ZodString>>;
         envOverrides: z.ZodOptional<z.ZodObject<{
             apiKey: z.ZodOptional<z.ZodString>;
             baseURL: z.ZodOptional<z.ZodString>;
@@ -60,7 +61,7 @@ export declare const providerCatalogJsonSchema: z.ZodObject<{
     capabilities: z.ZodObject<{
         text: z.ZodBoolean;
         streaming: z.ZodBoolean;
-        tools: z.ZodBoolean;
+        tools: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"model-dependent">]>;
         toolsWithStreaming: z.ZodBoolean;
         structuredOutput: z.ZodBoolean;
         structuredOutputWithTools: z.ZodBoolean;
@@ -83,7 +84,13 @@ export declare const providerCatalogJsonSchema: z.ZodObject<{
         timeoutErrorClass: z.ZodOptional<z.ZodLiteral<"provider">>;
         messageContentFormat: z.ZodOptional<z.ZodLiteral<"string">>;
         registryDefaultIgnoresModelEnvVar: z.ZodOptional<z.ZodBoolean>;
+        responseFormatDowngrade: z.ZodOptional<z.ZodLiteral<"json-schema-to-json-object">>;
     }, z.core.$strict>>;
+    timeouts: z.ZodOptional<z.ZodObject<{
+        generateMs: z.ZodOptional<z.ZodNumber>;
+        streamMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    autoSelectPriority: z.ZodOptional<z.ZodNumber>;
     setup: z.ZodObject<{
         url: z.ZodString;
         apiKeyFormat: z.ZodNullable<z.ZodString>;

package/dist/providers/catalog/schema.js

@@ -36,6 +36,7 @@ const catalogWireSchema = z
     baseURLTemplate: z.string().optional(),
     extraCredentials: z.array(z.string()).optional(),
     missingCredentialMessage: z.string().optional(),
+    apiKeyFallbackEnvVars: z.array(z.string()).optional(),
     envOverrides: z
         .strictObject({
         apiKey: z.string().optional(),
@@ -138,6 +139,11 @@ const catalogQuirksSchema = z.strictObject({
     timeoutErrorClass: z.literal("provider").optional(),
     messageContentFormat: z.literal("string").optional(),
     registryDefaultIgnoresModelEnvVar: z.boolean().optional(),
+    responseFormatDowngrade: z.literal("json-schema-to-json-object").optional(),
+});
+const catalogTimeoutsSchema = z.strictObject({
+    generateMs: z.number().optional(),
+    streamMs: z.number().optional(),
 });
 const catalogBillingPolicySchema = z.enum([
     "free-tier",
@@ -172,7 +178,7 @@ const catalogEvidenceSchema = z.strictObject({
 const catalogCapabilitiesSchema = z.strictObject({
     text: z.boolean(),
     streaming: z.boolean(),
-    tools: z.boolean(),
+    tools: z.union([z.boolean(), z.literal("model-dependent")]),
     toolsWithStreaming: z.boolean(),
     structuredOutput: z.boolean(),
     structuredOutputWithTools: z.boolean(),
@@ -331,6 +337,8 @@ export const providerCatalogJsonSchema = z.strictObject({
     capabilities: catalogCapabilitiesSchema,
     errorRules: z.array(catalogErrorRuleJsonSchema),
     quirks: catalogQuirksSchema.optional(),
+    timeouts: catalogTimeoutsSchema.optional(),
+    autoSelectPriority: z.number().optional(),
     setup: catalogSetupSchema,
     evidence: catalogEvidenceSchema,
 });

package/dist/providers/configuredOpenAICompat.d.ts

@@ -1,5 +1,5 @@
 import type { AIProviderName } from "../constants/enums.js";
-import type { OpenAICompatCatalogEntry, OpenAICompatChatRequest, OpenAICompatCredentials } from "../types/index.js";
+import type { OpenAICompatCatalogEntry, OpenAICompatChatRequest, OpenAICompatCredentials, OpenAICompatResponseFormat } from "../types/index.js";
 import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
 /**
  * Generic OpenAI-compatible provider driven entirely by an
@@ -11,13 +11,13 @@ import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
  * If a provider needs a real hook override (adjustRequestBody,
  * adjustBodyAfter400, getChatCompletionsURL, getAuthHeaders,
  * suppressResponseFormatWithTools, ...) it does NOT belong in the catalog —
- * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts).
+ * write a dedicated subclass instead (see azureOpenai.ts).
  *
  * The exception is a WIRE DIALECT: a vendor that speaks OpenAI for ordinary
  * chat but encodes one part of the request differently. Expressing that as
- * data (the catalog's `messageContentFormat`) keeps the provider a
- * one-JSON-file entry instead of promoting it to a hand-written subclass
- * over a single incompatibility.
+ * data (the catalog's `messageContentFormat` / `responseFormatDowngrade`)
+ * keeps the provider a one-JSON-file entry instead of promoting it to a
+ * hand-written subclass over a single incompatibility.
  *
  * Today that is Cloudflare Workers AI, whose OpenAI-compatible endpoint
  * accepts `messages[].content` only as a plain string — never the
@@ -28,6 +28,14 @@ import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
  * every tool round-trip fails. Normalizing content to a string below is the
  * whole fix: tools, tool_choice, the `tool` role and `tool_calls` are all
  * accepted as-is.
+ *
+ * The same shape covers DeepSeek: its `/chat/completions` rejects
+ * `response_format: { type: "json_schema" }` outright ("This response_format
+ * type is unavailable now"), but accepts `{ type: "json_object" }`. The
+ * catalog's `responseFormatDowngrade` quirk downgrades the request so
+ * `generate({ schema })` keeps working, matching the
+ * `supportsStructuredOutputs: false` behavior of the `@ai-sdk/openai-compatible`
+ * provider this replaced.
  */
 export declare class ConfiguredOpenAICompatProvider extends OpenAIChatCompletionsProvider {
     private readonly entry;
@@ -48,5 +56,6 @@ export declare class ConfiguredOpenAICompatProvider extends OpenAIChatCompletion
      */
     supportsTools(): boolean;
     protected adjustRequestBody(body: OpenAICompatChatRequest, modelId: string): OpenAICompatChatRequest;
+    protected adjustResponseFormat(rf: OpenAICompatResponseFormat | undefined, modelId: string): OpenAICompatResponseFormat | undefined;
     protected formatProviderError(error: unknown): Error;
 }

package/dist/providers/configuredOpenAICompat.js

@@ -33,13 +33,13 @@ const flattenMessageContent = (content) => {
  * If a provider needs a real hook override (adjustRequestBody,
  * adjustBodyAfter400, getChatCompletionsURL, getAuthHeaders,
  * suppressResponseFormatWithTools, ...) it does NOT belong in the catalog —
- * write a dedicated subclass instead (see deepseek.ts, azureOpenai.ts).
+ * write a dedicated subclass instead (see azureOpenai.ts).
  *
  * The exception is a WIRE DIALECT: a vendor that speaks OpenAI for ordinary
  * chat but encodes one part of the request differently. Expressing that as
- * data (the catalog's `messageContentFormat`) keeps the provider a
- * one-JSON-file entry instead of promoting it to a hand-written subclass
- * over a single incompatibility.
+ * data (the catalog's `messageContentFormat` / `responseFormatDowngrade`)
+ * keeps the provider a one-JSON-file entry instead of promoting it to a
+ * hand-written subclass over a single incompatibility.
  *
  * Today that is Cloudflare Workers AI, whose OpenAI-compatible endpoint
  * accepts `messages[].content` only as a plain string — never the
@@ -50,6 +50,14 @@ const flattenMessageContent = (content) => {
  * every tool round-trip fails. Normalizing content to a string below is the
  * whole fix: tools, tool_choice, the `tool` role and `tool_calls` are all
  * accepted as-is.
+ *
+ * The same shape covers DeepSeek: its `/chat/completions` rejects
+ * `response_format: { type: "json_schema" }` outright ("This response_format
+ * type is unavailable now"), but accepts `{ type: "json_object" }`. The
+ * catalog's `responseFormatDowngrade` quirk downgrades the request so
+ * `generate({ schema })` keeps working, matching the
+ * `supportsStructuredOutputs: false` behavior of the `@ai-sdk/openai-compatible`
+ * provider this replaced.
  */
 export class ConfiguredOpenAICompatProvider extends OpenAIChatCompletionsProvider {
     entry;
@@ -115,6 +123,13 @@ export class ConfiguredOpenAICompatProvider extends OpenAIChatCompletionsProvide
             })),
         };
     }
+    adjustResponseFormat(rf, modelId) {
+        if (this.entry.responseFormatDowngrade === "json-schema-to-json-object" &&
+            rf?.type === "json_schema") {
+            return { type: "json_object" };
+        }
+        return super.adjustResponseFormat(rf, modelId);
+    }
     formatProviderError(error) {
         // classifyProviderError hard-codes TimeoutError -> NetworkError ahead
         // of any rule table and does not allow a per-provider override. An

package/dist/providers/embeddingResponseParsing.d.ts

@@ -0,0 +1 @@
+export declare function parseIndexedEmbeddingsResponse(data: unknown, inputCount: number, providerLabel: string, makeError: (message: string) => Error): number[][];

package/dist/providers/embeddingResponseParsing.js

@@ -0,0 +1,47 @@
+/**
+ * Shared embeddings-response validation for Voyage and Jina — both call
+ * POST /embeddings with an identical `{input, model}` body and get back an
+ * identical `{data: [{embedding, index}]}` shape, and both had byte-identical
+ * validation logic (same three message templates, same sort-by-index +
+ * 0..n-1 coverage check) before this was factored out.
+ *
+ * A plain function, not a shared base class: Voyage throws typed
+ * `ProviderError` here, Jina throws plain `Error` (a real, pre-existing
+ * inconsistency between the two — not something this refactor silently
+ * fixes). `makeError` preserves each provider's exact existing behavior;
+ * `providerLabel` preserves each provider's exact existing message text
+ * ("Voyage ..." / "Jina ...").
+ */
+const isIndexedEmbedding = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const { embedding, index } = value;
+    return (Number.isInteger(index) &&
+        Array.isArray(embedding) &&
+        embedding.every((n) => typeof n === "number" && Number.isFinite(n)));
+};
+export function parseIndexedEmbeddingsResponse(data, inputCount, providerLabel, makeError) {
+    const entries = typeof data === "object" && data !== null
+        ? data.data
+        : undefined;
+    if (!Array.isArray(entries) || entries.length === 0) {
+        throw makeError(`${providerLabel} embeddings response missing data`);
+    }
+    if (entries.length !== inputCount) {
+        throw makeError(`${providerLabel} embeddings response count mismatch: expected ${inputCount}, got ${entries.length}`);
+    }
+    const malformed = entries.findIndex((entry) => !isIndexedEmbedding(entry));
+    if (malformed !== -1) {
+        throw makeError(`${providerLabel} embeddings response entry ${malformed} is not an {index, embedding: number[]} object`);
+    }
+    const sorted = entries
+        .slice()
+        .sort((a, b) => a.index - b.index);
+    for (let i = 0; i < sorted.length; i++) {
+        if (sorted[i].index !== i) {
+            throw makeError(`${providerLabel} embeddings response has unexpected index ordering: position ${i} has index ${sorted[i].index}`);
+        }
+    }
+    return sorted.map((d) => d.embedding);
+}

package/dist/providers/ideogram.js

@@ -5,6 +5,8 @@ import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { AuthenticationError, ProviderError, RateLimitError, } from "../types/index.js";
 import { logger } from "../utils/logger.js";
 import { createIdeogramConfig, getProviderModel, validateApiKey, } from "../utils/providerConfig.js";
+import { MAX_IMAGE_BYTES, readBoundedBuffer } from "../utils/sizeGuard.js";
+import { assertSafeUrl } from "../utils/ssrfGuard.js";
 const IDEOGRAM_DEFAULT_BASE_URL = "https://api.ideogram.ai";
 const REQUEST_TIMEOUT_MS = 120_000;
 const getIdeogramApiKey = () => validateApiKey(createIdeogramConfig());
@@ -132,6 +134,10 @@ export class IdeogramProvider extends BaseProvider {
         if (!url) {
             throw new Error("Ideogram returned no image URL");
         }
+        // Guard the API-returned URL before fetching (provider-returned URLs
+        // carry the same SSRF risk as caller-supplied ones) — matches Recraft's
+        // equivalent download path.
+        await assertSafeUrl(url);
         // Download the image and convert to base64 to match the imageOutput
         // contract used by other image-gen providers. Apply a 60s timeout so the
         // download cannot hang indefinitely.
@@ -155,7 +161,7 @@ export class IdeogramProvider extends BaseProvider {
         if (!dl.ok) {
             throw new Error(`Failed to download Ideogram image: ${dl.status}`);
         }
-        const buffer = Buffer.from(await dl.arrayBuffer());
+        const buffer = await readBoundedBuffer(dl, MAX_IMAGE_BYTES, "Ideogram image");
         const base64 = buffer.toString("base64");
         const generationTimeMs = Date.now() - startTime;
         logger.info(`[IdeogramProvider] Generated image (${buffer.length} bytes) in ${generationTimeMs}ms — model ${this.modelName}`);

package/dist/providers/jina.js

@@ -1,6 +1,7 @@
 import { JinaModels } from "../constants/enums.js";
 import { BaseProvider } from "../core/baseProvider.js";
 import { isNeuroLink } from "../neurolink.js";
+import { parseIndexedEmbeddingsResponse } from "./embeddingResponseParsing.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { AuthenticationError, InvalidModelError, ProviderError, RateLimitError, } from "../types/index.js";
 import { logger } from "../utils/logger.js";
@@ -190,21 +191,11 @@ export class JinaProvider extends BaseProvider {
             throw this.formatProviderError(new Error(`Jina embeddings failed: ${response.status} — ${text}`));
         }
         const data = (await response.json());
-        if (!data.data || data.data.length === 0) {
-            throw new Error("Jina embeddings response missing data");
-        }
-        // Validate that the response covers all requested inputs.
-        if (data.data.length !== inputs.length) {
-            throw new Error(`Jina embeddings response count mismatch: expected ${inputs.length}, got ${data.data.length}`);
-        }
-        // Sort by index and verify sequential coverage (0 … n-1).
-        const sorted = data.data.slice().sort((a, b) => a.index - b.index);
-        for (let i = 0; i < sorted.length; i++) {
-            if (sorted[i].index !== i) {
-                throw new Error(`Jina embeddings response has unexpected index ordering: position ${i} has index ${sorted[i].index}`);
-            }
-        }
-        return sorted.map((d) => d.embedding);
+        // Sorts by index and verifies sequential 0..n-1 coverage. Note: throws
+        // plain Error, not ProviderError, unlike Voyage's equivalent — a real,
+        // pre-existing inconsistency between the two, preserved as-is rather
+        // than silently "fixed" by this refactor.
+        return parseIndexedEmbeddingsResponse(data, inputs.length, "Jina", (message) => new Error(message));
     }
     async validateConfiguration() {
         return typeof this.apiKey === "string" && this.apiKey.trim().length > 0;

package/dist/providers/llamaCpp.js

@@ -1,8 +1,9 @@
-import { NetworkError, ProviderError } from "../types/index.js";
+import { ProviderError } from "../types/index.js";
 import { classifyProviderError, DEFAULT_ERROR_RULES, } from "../utils/errorClassifier.js";
 import { logger } from "../utils/logger.js";
 import { redactUrlCredentials } from "../utils/logSanitize.js";
 import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
+import { buildLocalUnreachableErrorRule } from "./localRuntimeOpenAICompat.js";
 const LLAMACPP_DEFAULT_BASE_URL = "http://localhost:8080/v1";
 const LLAMACPP_PLACEHOLDER_KEY = "llamacpp";
 const getLlamaCppBaseURL = () => {
@@ -52,21 +53,9 @@ export class LlamaCppProvider extends OpenAIChatCompletionsProvider {
         return ["loaded-model"];
     }
     formatProviderError(error) {
-        // `code`/`cause.code` aren't part of ProviderErrorContext, so they're read
-        // off the raw error here (mirrors ollama's `responseBody` extraction) for
-        // the ECONNREFUSED rule below, which the pre-migration code also checked
-        // via a duck-typed error code in addition to the message text.
-        const errorRecord = error;
-        const cause = errorRecord?.cause ?? {};
-        const code = (errorRecord?.code ?? cause?.code);
         const rules = [
-            {
-                match: (ctx) => code === "ECONNREFUSED" ||
-                    /ECONNREFUSED|Failed to fetch|fetch failed/.test(ctx.message),
-                errorClass: NetworkError,
-                message: () => `llama.cpp server not reachable at ${redactUrlCredentials(this.config.baseURL)}. ` +
-                    "Start it with: ./llama-server -m model.gguf --port 8080",
-            },
+            buildLocalUnreachableErrorRule(error, () => `llama.cpp server not reachable at ${redactUrlCredentials(this.config.baseURL)}. ` +
+                "Start it with: ./llama-server -m model.gguf --port 8080"),
             {
                 match: (ctx) => /400/.test(ctx.message),
                 errorClass: ProviderError,

package/dist/providers/lmStudio.js

@@ -1,8 +1,9 @@
-import { InvalidModelError, NetworkError } from "../types/index.js";
+import { InvalidModelError } from "../types/index.js";
 import { classifyProviderError, DEFAULT_ERROR_RULES, } from "../utils/errorClassifier.js";
 import { logger } from "../utils/logger.js";
 import { redactUrlCredentials } from "../utils/logSanitize.js";
 import { OpenAIChatCompletionsProvider } from "./openaiChatCompletionsBase.js";
+import { buildLocalUnreachableErrorRule } from "./localRuntimeOpenAICompat.js";
 const LM_STUDIO_DEFAULT_BASE_URL = "http://localhost:1234/v1";
 const LM_STUDIO_PLACEHOLDER_KEY = "lm-studio";
 const FALLBACK_MODEL = "local-model";
@@ -47,21 +48,9 @@ export class LMStudioProvider extends OpenAIChatCompletionsProvider {
         return FALLBACK_MODEL;
     }
     formatProviderError(error) {
-        // `code`/`cause.code` aren't part of ProviderErrorContext, so they're read
-        // off the raw error here (mirrors ollama's `responseBody` extraction) for
-        // the ECONNREFUSED rule below, which the pre-migration code also checked
-        // via a duck-typed error code in addition to the message text.
-        const errorRecord = error;
-        const cause = errorRecord?.cause ?? {};
-        const code = (errorRecord?.code ?? cause?.code);
         const rules = [
-            {
-                match: (ctx) => code === "ECONNREFUSED" ||
-                    /ECONNREFUSED|Failed to fetch|fetch failed/.test(ctx.message),
-                errorClass: NetworkError,
-                message: () => `LM Studio server not reachable at ${redactUrlCredentials(this.config.baseURL)}. ` +
-                    `Open the LM Studio app, load a model, and click "Start Server".`,
-            },
+            buildLocalUnreachableErrorRule(error, () => `LM Studio server not reachable at ${redactUrlCredentials(this.config.baseURL)}. ` +
+                `Open the LM Studio app, load a model, and click "Start Server".`),
             {
                 match: (ctx) => /model_not_found|404/.test(ctx.message),
                 errorClass: InvalidModelError,

package/dist/providers/localRuntimeOpenAICompat.d.ts

@@ -0,0 +1,16 @@
+import type { ProviderErrorRule } from "../types/index.js";
+/**
+ * Shared error-rule builder for local-runtime OpenAI-compatible providers —
+ * Ollama, LM Studio, llama.cpp. All three had byte-identical connection-
+ * refused predicates (including the duck-typed `code`/`cause.code`
+ * extraction, since none of that lives on ProviderErrorContext) before this
+ * factored it out. A plain function, not a shared base class: the
+ * `neurolink/provider-base-class` lint rule requires every provider to
+ * extend BaseProvider or OpenAIChatCompletionsProvider directly, so the
+ * three keep their existing class hierarchy and just call this from their
+ * own `formatProviderError()`.
+ *
+ * `message` stays per-vendor (each provider's own exact wording, unchanged)
+ * — only the match predicate and errorClass were ever duplicated.
+ */
+export declare function buildLocalUnreachableErrorRule(error: unknown, message: () => string): ProviderErrorRule;

package/dist/providers/localRuntimeOpenAICompat.js

@@ -0,0 +1,26 @@
+import { NetworkError } from "../types/index.js";
+/**
+ * Shared error-rule builder for local-runtime OpenAI-compatible providers —
+ * Ollama, LM Studio, llama.cpp. All three had byte-identical connection-
+ * refused predicates (including the duck-typed `code`/`cause.code`
+ * extraction, since none of that lives on ProviderErrorContext) before this
+ * factored it out. A plain function, not a shared base class: the
+ * `neurolink/provider-base-class` lint rule requires every provider to
+ * extend BaseProvider or OpenAIChatCompletionsProvider directly, so the
+ * three keep their existing class hierarchy and just call this from their
+ * own `formatProviderError()`.
+ *
+ * `message` stays per-vendor (each provider's own exact wording, unchanged)
+ * — only the match predicate and errorClass were ever duplicated.
+ */
+export function buildLocalUnreachableErrorRule(error, message) {
+    const errorRecord = error;
+    const cause = errorRecord?.cause ?? {};
+    const code = (errorRecord?.code ?? cause?.code);
+    return {
+        match: (ctx) => code === "ECONNREFUSED" ||
+            /ECONNREFUSED|Failed to fetch|fetch failed/.test(ctx.message),
+        errorClass: NetworkError,
+        message,
+    };
+}

package/dist/providers/ollama/client.js

@@ -6,6 +6,7 @@ import { logger } from "../../utils/logger.js";
 import { redactUrlCredentials } from "../../utils/logSanitize.js";
 import { createTimeoutController, parseTimeout, TimeoutError, } from "../../utils/timeout.js";
 import { OpenAIChatCompletionsProvider } from "../openaiChatCompletionsBase.js";
+import { buildLocalUnreachableErrorRule } from "../localRuntimeOpenAICompat.js";
 import { stripTrailingSlash } from "../openaiChatCompletionsClient.js";
 import { DEFAULT_OLLAMA_MODEL } from "./constants.js";
 // Ollama serves its OpenAI-compatible surface under `/v1` (/v1/chat/completions,
@@ -97,16 +98,9 @@ export class OllamaProvider extends OpenAIChatCompletionsProvider {
         const responseBody = typeof errorRecord?.responseBody === "string"
             ? errorRecord.responseBody
             : "";
-        const cause = errorRecord?.cause ?? {};
-        const code = (errorRecord?.code ?? cause?.code);
         const rules = [
-            {
-                match: (ctx) => code === "ECONNREFUSED" ||
-                    /ECONNREFUSED|Failed to fetch|fetch failed/.test(ctx.message),
-                errorClass: NetworkError,
-                message: () => `Cannot connect to Ollama at ${redactUrlCredentials(this.config.baseURL)}. ` +
-                    `Install Ollama (https://ollama.com), start it with 'ollama serve', then try again.`,
-            },
+            buildLocalUnreachableErrorRule(error, () => `Cannot connect to Ollama at ${redactUrlCredentials(this.config.baseURL)}. ` +
+                `Install Ollama (https://ollama.com), start it with 'ollama serve', then try again.`),
             // The base client (buildAPIError) attaches statusCode + responseBody to
             // HTTP failures. Distinguish a genuine missing-model error (give 'ollama
             // pull' guidance) from a bare endpoint-mismatch 404 (wrong base URL / not

package/dist/providers/openaiChatCompletionsBase.d.ts

@@ -5,9 +5,9 @@
  * quirks (env var names, default model, error mapping).
  *
  * Currently extended by:
- *   - OpenAICompatibleProvider (generic /v1/chat/completions backend)
- *   - LiteLLMProvider          (LiteLLM proxy server)
- *   - DeepSeekProvider         (api.deepseek.com)
+ *   - OpenAICompatibleProvider   (generic /v1/chat/completions backend)
+ *   - LiteLLMProvider            (LiteLLM proxy server)
+ *   - ConfiguredOpenAICompatProvider (JSON-catalog providers, incl. deepseek)
  *
  * Subclasses provide:
  *   - getProviderName() / getDefaultModel() / formatProviderError() (abstract)

package/dist/providers/openaiChatCompletionsBase.js

@@ -5,9 +5,9 @@
  * quirks (env var names, default model, error mapping).
  *
  * Currently extended by:
- *   - OpenAICompatibleProvider (generic /v1/chat/completions backend)
- *   - LiteLLMProvider          (LiteLLM proxy server)
- *   - DeepSeekProvider         (api.deepseek.com)
+ *   - OpenAICompatibleProvider   (generic /v1/chat/completions backend)
+ *   - LiteLLMProvider            (LiteLLM proxy server)
+ *   - ConfiguredOpenAICompatProvider (JSON-catalog providers, incl. deepseek)
  *
  * Subclasses provide:
  *   - getProviderName() / getDefaultModel() / formatProviderError() (abstract)
@@ -1055,7 +1055,14 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             usage: {
                 input: inputTokens,
                 output: outputTokens,
-                total: inputTokens + outputTokens,
+                // `inputTokens` is the disjoint (uncached) figure — doGenerate
+                // already subtracts the overlapping prompt_tokens_details.cached_tokens
+                // subset before handing it to the loop — so cache tokens must be
+                // added back in here to keep `total` billing-complete.
+                total: inputTokens +
+                    outputTokens +
+                    loop.cacheReadTokens +
+                    loop.cacheWriteTokens,
                 // doGenerate reads prompt_tokens_details.cached_tokens, and the loop
                 // carries the counters out; discarding them here billed cached input
                 // at the full rate in calculateCost and made cache effectiveness
@@ -1492,10 +1499,18 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                 if (!loopPromise) {
                     const input = part.usage.inputTokens.total ?? 0;
                     const output = part.usage.outputTokens.total ?? 0;
+                    // `total` is cache-INCLUSIVE (OpenAI-style prompt_tokens), so the
+                    // cached portion has to be split out here the same way
+                    // doGenerate/toDeferredUsage do — otherwise this branch bills the
+                    // cached tokens at the full input rate instead of the cheaper
+                    // cacheRead rate. Clamped like the other call sites in this file
+                    // in case a gateway reports cacheRead > total.
+                    const cacheRead = Math.min(part.usage.inputTokens.cacheRead ?? 0, input);
                     resolveUsage({
-                        promptTokens: input,
+                        promptTokens: input - cacheRead,
                         completionTokens: output,
                         totalTokens: input + output,
+                        ...(cacheRead > 0 ? { cacheReadTokens: cacheRead } : {}),
                     });
                     resolveFinish(part.finishReason.unified);
                 }