@juspay/neurolink 10.3.0 → 10.4.0

package/dist/lib/providers/openaiChatCompletionsBase.js

@@ -17,6 +17,9 @@
  * Nothing here imports from "ai" or "@ai-sdk/*". The base class is a
  * direct HTTP client + multi-step tool-execution loop driven by SSE.
  */
+import { getRuntimeContextWindow, getRuntimeOutputCeiling, registerRuntimeContextWindow, } from "../constants/contextWindows.js";
+import { isContextOverflowError, parseProviderOverflowDetails, } from "../context/errorDetection.js";
+import { ContextBudgetExceededError } from "../context/errors.js";
 import { BaseProvider } from "../core/baseProvider.js";
 import { DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
@@ -24,11 +27,17 @@ import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { logger } from "../utils/logger.js";
 import { NoOutputGeneratedError } from "../utils/generationErrors.js";
 import { buildNoOutputSentinel, stampNoOutputSpan, } from "../utils/noOutputSentinel.js";
-import { composeAbortSignals, createTimeoutController, mergeAbortSignals, } from "../utils/timeout.js";
+import { composeAbortSignalsScoped, createTimeoutController, mergeAbortSignals, } from "../utils/timeout.js";
 import { emitToolEndFromStepFinish } from "../utils/toolEndEmitter.js";
 import { resolveToolChoice } from "../utils/toolChoice.js";
 import { transformToolExecutions } from "../utils/transformationUtils.js";
-import { buildAPIError, buildBody, buildToolsForOpenAI, createChunkQueue, createDeferredAnalytics, ensureJsonWordInBody, mapNeuroLinkToolChoice, mergeUsage, messageBuilderToOpenAI, parseSSEStream, stringifyToolOutput, stripTrailingSlash, v3ResponseFormatToOpenAI, v3ToolChoiceToOpenAI, v3ToolsToOpenAI, } from "./openaiChatCompletionsClient.js";
+import { buildAPIError, buildBody, buildToolsForOpenAI, buildWireToolNameMaps, createChunkQueue, createDeferredAnalytics, ensureJsonWordInBody, estimateWireTokens, mapNeuroLinkToolChoice, mergeUsage, messageBuilderToOpenAI, parseSSEStream, stringifyToolOutput, stripTrailingSlash, v3ResponseFormatToOpenAI, v3ToolChoiceToOpenAI, v3ToolsToOpenAI, } from "./openaiChatCompletionsClient.js";
+/**
+ * Safety margin (tokens) when fitting `max_tokens` to a runtime-discovered
+ * context window: the char-based input estimate and the backend's own prompt
+ * framing differ by a few hundred tokens, so an exact fit would still 400.
+ */
+const WINDOW_FIT_MARGIN_TOKENS = 512;
 /**
  * Abstract HTTP+SSE provider for OpenAI chat-completions-shaped endpoints.
  */
@@ -114,6 +123,106 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
     adjustBodyAfter400(_body, _error) {
         return undefined;
     }
+    /**
+     * Fit the outgoing `max_tokens` to what the target deployment can actually
+     * accept, using ONLY runtime-discovered limits — static table values are
+     * guesses, and hard-enforcing a guess would falsely reject requests the
+     * real deployment accepts:
+     *
+     *   effective = min(requested, discovered output ceiling,
+     *                   discovered window − estimated input − margin)
+     *
+     * Returns the caller's value untouched when nothing was discovered, and
+     * `undefined` when the caller sent nothing and no ceiling is known (the
+     * wire then omits max_tokens and the backend applies its own default — no
+     * invented numbers). Throws ContextBudgetExceededError when the estimated
+     * input ALONE exceeds a discovered window: that request cannot succeed,
+     * and failing fast with honest numbers beats a guaranteed provider 400
+     * (plus any proxy-side fallback cascade) after a full round-trip.
+     */
+    resolveWireMaxTokens(modelId, requested, messages, tools) {
+        const ceiling = getRuntimeOutputCeiling(this.providerName, modelId);
+        let effective = requested;
+        if (ceiling !== undefined &&
+            (effective === undefined || effective > ceiling)) {
+            if (effective !== undefined) {
+                logger.debug(`${this.providerName}: clamping max_tokens ${effective} to the advertised ${modelId} output ceiling ${ceiling}`);
+            }
+            effective = ceiling;
+        }
+        const window = getRuntimeContextWindow(this.providerName, modelId);
+        if (window !== undefined) {
+            const estimatedInput = estimateWireTokens(messages, tools, this.providerName);
+            const fit = window - estimatedInput - WINDOW_FIT_MARGIN_TOKENS;
+            if (fit <= 0) {
+                throw new ContextBudgetExceededError(`Estimated input (${estimatedInput} tokens) alone exceeds the ` +
+                    `${this.providerName}/${modelId} context window advertised by ` +
+                    `the serving infrastructure (${window} tokens). Reduce the ` +
+                    `prompt/conversation size — no max_tokens value can make this ` +
+                    `request fit.`, {
+                    estimatedTokens: estimatedInput,
+                    availableTokens: Math.max(0, window - WINDOW_FIT_MARGIN_TOKENS),
+                    stagesUsed: [],
+                    breakdown: {},
+                });
+            }
+            if (effective !== undefined && effective > fit) {
+                logger.warn(`${this.providerName}: max_tokens ${effective} cannot fit the ` +
+                    `${modelId} window (${window}) with ~${estimatedInput} input ` +
+                    `tokens — re-fitting to ${fit}`);
+                effective = fit;
+            }
+        }
+        return effective;
+    }
+    /**
+     * Learn from a provider context-overflow 400 and, when possible, produce a
+     * corrected body for the one-shot retry slot. Two dynamic effects, zero
+     * static data:
+     *
+     *  - the window stated in the error is registered with the runtime
+     *    resolver, so every later budget check / compaction / max_tokens fit
+     *    uses the backend's own number — self-healing even when a discovery
+     *    endpoint (`/model/info`) is absent or unauthorized;
+     *  - when the error also states the real input size (vllm/LiteLLM
+     *    phrasing) and the body carried `max_tokens`, it is re-fit to
+     *    `window − input − margin` and the request retried once.
+     *
+     * Returns undefined when the error is not an overflow, or when no smaller
+     * `max_tokens` can make the request fit (input alone too large) — the
+     * original error then propagates unchanged.
+     */
+    correctBodyAfterContextOverflow(body, error) {
+        if (!isContextOverflowError(error)) {
+            return undefined;
+        }
+        const details = parseProviderOverflowDetails(error) ??
+            parseProviderOverflowDetails(error.responseBody);
+        if (!details || details.budgetTokens <= 0) {
+            return undefined;
+        }
+        registerRuntimeContextWindow(this.providerName, body.model, details.budgetTokens);
+        // When the body carried no max_tokens (server-defaulted output), the
+        // vllm/LiteLLM phrasing still states what the backend counted — use it
+        // so those requests get a re-fit retry too instead of propagating.
+        const previousMaxTokens = typeof body.max_tokens === "number"
+            ? body.max_tokens
+            : details.requestedOutputTokens;
+        if (previousMaxTokens === undefined || details.actualTokens <= 0) {
+            return undefined;
+        }
+        const refit = details.budgetTokens - details.actualTokens - WINDOW_FIT_MARGIN_TOKENS;
+        if (refit <= 0 || refit >= previousMaxTokens) {
+            return undefined;
+        }
+        logger.warn(`${this.providerName}: ${body.model} rejected the request as over-window — retrying once with max_tokens re-fit from the provider's own numbers`, {
+            window: details.budgetTokens,
+            inputTokens: details.actualTokens,
+            previousMaxTokens,
+            refitMaxTokens: refit,
+        });
+        return { ...body, max_tokens: refit };
+    }
     /**
      * Hook called once at the start of every `executeStream` invocation.
      * Return lifecycle listeners (onUsage / onFinish) to receive deferred
@@ -238,6 +347,8 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         const adjustResponseFormat = this.adjustResponseFormat.bind(this);
         const adjustRequestBody = this.adjustRequestBody.bind(this);
         const adjustBodyAfter400 = this.adjustBodyAfter400.bind(this);
+        const correctBodyAfterContextOverflow = this.correctBodyAfterContextOverflow.bind(this);
+        const resolveWireMaxTokens = this.resolveWireMaxTokens.bind(this);
         const suppressResponseFormatWithTools = this.suppressResponseFormatWithTools.bind(this);
         const getTimeoutForOptions = (opts) => this.getTimeout((opts ?? {}));
         return {
@@ -246,7 +357,13 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             modelId,
             supportedUrls: {},
             doGenerate: async (options) => {
-                const baseMessages = messageBuilderToOpenAI(options.prompt);
+                // Wire-name mapping: only materializes when at least one tool name
+                // is outside the OpenAI-compatible alphabet (see
+                // buildWireToolNameMaps) — the common all-valid case is a no-op.
+                const wireNameMaps = buildWireToolNameMaps((options.tools ?? [])
+                    .filter((t) => t.type === "function")
+                    .map((t) => t.name));
+                const baseMessages = messageBuilderToOpenAI(options.prompt, wireNameMaps?.toWire);
                 const hasTools = Array.isArray(options.tools) && options.tools.length > 0;
                 const responseFormat = options.responseFormat &&
                     !(hasTools && suppressResponseFormatWithTools())
@@ -256,11 +373,15 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                 // so the json_object word guard reflects whatever a subclass left on
                 // the wire (it may rewrite response_format/messages), not an
                 // intermediate state.
+                const wireTools = v3ToolsToOpenAI(options.tools, wireNameMaps?.toWire);
+                // Fit max_tokens to the runtime-discovered output ceiling and
+                // context window (no-op when nothing was discovered).
+                const wireMaxTokens = resolveWireMaxTokens(modelId, options.maxOutputTokens, baseMessages, wireTools);
                 const body = ensureJsonWordInBody(adjustRequestBody(buildBody({
                     modelId,
                     messages: baseMessages,
                     options: adjustBuildBodyOptions(modelId, {
-                        maxTokens: options.maxOutputTokens,
+                        maxTokens: wireMaxTokens,
                         temperature: options.temperature,
                         topP: options.topP,
                         presencePenalty: options.presencePenalty,
@@ -268,18 +389,33 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                         seed: options.seed,
                         stopSequences: options.stopSequences,
                     }),
-                    tools: v3ToolsToOpenAI(options.tools),
+                    tools: wireTools,
                     ...(options.toolChoice
-                        ? { toolChoice: v3ToolChoiceToOpenAI(options.toolChoice) }
+                        ? {
+                            toolChoice: v3ToolChoiceToOpenAI(options.toolChoice, wireNameMaps?.toWire),
+                        }
                         : {}),
                     streaming: false,
                     ...(responseFormat ? { responseFormat } : {}),
                 }), modelId));
-                const timeoutController = createTimeoutController(getTimeoutForOptions(options), providerName, "generate");
-                const composedSignal = composeAbortSignals(options.abortSignal, timeoutController?.controller.signal);
-                let res;
+                // Per-step timeout: the AI-SDK V3 call options never carry `timeout`,
+                // so resolving from them always returned the provider default — a
+                // caller's explicit `timeout: "15m"` bounded the outer loop but each
+                // step request stayed capped at the default (litellm: 5m). The
+                // orchestrator forwards the caller's resolved timeout via
+                // providerOptions.neurolink.timeoutMs; prefer it when present.
+                const nlStepTimeoutMs = options.providerOptions?.neurolink?.timeoutMs;
+                const timeoutController = createTimeoutController(typeof nlStepTimeoutMs === "number"
+                    ? nlStepTimeoutMs
+                    : getTimeoutForOptions(options), providerName, "generate");
+                // Scoped composition: a plain AbortSignal.any per step accumulates
+                // registrations on the long-lived generate-call signal for the whole
+                // turn (MaxListenersExceededWarning at 10+ steps); dispose() detaches
+                // this step's listeners the moment the request settles.
+                const { signal: composedSignal, dispose: disposeComposedSignal } = composeAbortSignalsScoped(options.abortSignal, timeoutController?.controller.signal);
+                let json;
                 try {
-                    res = await fetchImpl(url, {
+                    let res = await fetchImpl(url, {
                         method: "POST",
                         headers: {
                             "Content-Type": "application/json",
@@ -290,14 +426,17 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                     });
                     if (!res.ok) {
                         const apiErr = await buildAPIError(url, body, res);
-                        // One-shot 400 retry: a subclass may strip a rejected field and
-                        // return a modified body (e.g. NIM's chat_template /
-                        // reasoning_budget). The retry runs under the SAME timeout
-                        // controller as the first attempt, so the configured timeout caps
-                        // the overall call — matching the streaming path, which reuses
-                        // its composed signal for the retry.
+                        // One-shot 400 retry. The overflow corrector runs FIRST (it can
+                        // re-fit max_tokens from the provider's own numbers and also
+                        // self-heals the runtime window registry); otherwise a subclass
+                        // may strip a rejected field and return a modified body (e.g.
+                        // NIM's chat_template / reasoning_budget). The retry runs under
+                        // the SAME timeout controller as the first attempt, so the
+                        // configured timeout caps the overall call — matching the
+                        // streaming path, which reuses its composed signal for the retry.
                         const retryBody = res.status === 400
-                            ? adjustBodyAfter400(body, apiErr)
+                            ? (correctBodyAfterContextOverflow(body, apiErr) ??
+                                adjustBodyAfter400(body, apiErr))
                             : undefined;
                         if (!retryBody) {
                             throw apiErr;
@@ -315,11 +454,16 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                             throw await buildAPIError(url, retryBody, res);
                         }
                     }
+                    // Body read stays INSIDE the timeout window: it previously ran
+                    // after cleanup(), so a response whose headers arrived but whose
+                    // body stalled mid-transfer was bounded by nothing but the caller's
+                    // outer wall-clock.
+                    json = (await res.json());
                 }
                 finally {
                     timeoutController?.cleanup();
+                    disposeComposedSignal();
                 }
-                const json = (await res.json());
                 const choice = json.choices?.[0];
                 const text = (typeof choice?.message?.content === "string"
                     ? choice.message.content
@@ -341,7 +485,9 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                     content.push({
                         type: "tool-call",
                         toolCallId: tc.id,
-                        toolName: tc.function.name,
+                        // Reverse-map wire names so tool lookup/execution and results
+                        // reported to the caller use the registered names.
+                        toolName: wireNameMaps?.fromWire.get(tc.function.name) ?? tc.function.name,
                         input: tc.function.arguments ?? "",
                     });
                 }
@@ -412,6 +558,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         ]).signal;
         let modelId;
         let toolsRecord;
+        let wireNameMaps;
         let openAITools;
         let openAIToolChoice;
         let conversation;
@@ -421,12 +568,17 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             toolsRecord = shouldUseTools
                 ? options.tools || (await this.getAllTools())
                 : {};
+            // Wire-name mapping: only materializes when a registered tool name is
+            // outside the OpenAI-compatible alphabet (see buildWireToolNameMaps).
+            wireNameMaps = shouldUseTools
+                ? buildWireToolNameMaps(Object.keys(toolsRecord))
+                : undefined;
             openAITools = shouldUseTools
-                ? buildToolsForOpenAI(toolsRecord)
+                ? buildToolsForOpenAI(toolsRecord, wireNameMaps?.toWire)
                 : undefined;
-            openAIToolChoice = mapNeuroLinkToolChoice(resolveToolChoice(options, toolsRecord, shouldUseTools));
+            openAIToolChoice = mapNeuroLinkToolChoice(resolveToolChoice(options, toolsRecord, shouldUseTools), wireNameMaps?.toWire);
             const initialMessages = await this.buildMessagesForStream(options);
-            conversation = messageBuilderToOpenAI(initialMessages);
+            conversation = messageBuilderToOpenAI(initialMessages, wireNameMaps?.toWire);
         }
         catch (setupErr) {
             timeoutController?.cleanup();
@@ -453,6 +605,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             openAITools,
             openAIToolChoice,
             toolsRecord,
+            toolNameFromWire: wireNameMaps?.fromWire,
             emitter,
             toolsUsed,
             toolExecutionSummaries,
@@ -573,7 +726,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         return result;
     }
     async runStreamLoop(args) {
-        const { maxSteps, modelId, url, fetchImpl, abortSignal, options, conversation, openAITools, openAIToolChoice, toolsRecord, emitter, toolsUsed, toolExecutionSummaries, pushChunk, resolveUsage, resolveFinish, } = args;
+        const { maxSteps, modelId, url, fetchImpl, abortSignal, options, conversation, openAITools, openAIToolChoice, toolsRecord, toolNameFromWire, emitter, toolsUsed, toolExecutionSummaries, pushChunk, resolveUsage, resolveFinish, } = args;
         try {
             let stepFinish = null;
             let stepUsage;
@@ -600,6 +753,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                     stepResult,
                     conversation,
                     toolsRecord,
+                    toolNameFromWire,
                     emitter,
                     toolsUsed,
                     toolExecutionSummaries,
@@ -629,10 +783,17 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         }
     }
     async streamOneStep(args) {
+        // Per-step max_tokens fit: the conversation grows every step of the
+        // tool loop, so the window fit is recomputed per request (no-op when
+        // nothing was runtime-discovered).
+        const wireMaxTokens = this.resolveWireMaxTokens(args.modelId, args.options.maxTokens ?? undefined, args.conversation, args.openAITools);
+        const stepOptions = wireMaxTokens !== args.options.maxTokens
+            ? { ...args.options, maxTokens: wireMaxTokens }
+            : args.options;
         const body = ensureJsonWordInBody(this.adjustRequestBody(buildBody({
             modelId: args.modelId,
             messages: args.conversation,
-            options: this.adjustBuildBodyOptions(args.modelId, args.options),
+            options: this.adjustBuildBodyOptions(args.modelId, stepOptions),
             tools: args.openAITools,
             ...(args.openAIToolChoice !== undefined
                 ? { toolChoice: args.openAIToolChoice }
@@ -650,10 +811,13 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         });
         if (!res.ok) {
             const apiErr = await buildAPIError(args.url, body, res);
-            // One-shot 400 retry — same hook as the doGenerate path (e.g. NIM
-            // strips chat_template/reasoning_budget when a model rejects them).
+            // One-shot 400 retry — overflow corrector first (re-fits max_tokens
+            // from the provider's own numbers + self-heals the window registry),
+            // then the subclass hook (e.g. NIM strips chat_template /
+            // reasoning_budget when a model rejects them).
             const retryBody = res.status === 400
-                ? this.adjustBodyAfter400(body, apiErr)
+                ? (this.correctBodyAfterContextOverflow(body, apiErr) ??
+                    this.adjustBodyAfter400(body, apiErr))
                 : undefined;
             if (!retryBody) {
                 throw apiErr;
@@ -683,7 +847,7 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
         });
     }
     async executeToolBatch(args) {
-        const { stepResult, conversation, toolsRecord, emitter, toolsUsed, toolExecutionSummaries, options, } = args;
+        const { stepResult, conversation, toolsRecord, toolNameFromWire, emitter, toolsUsed, toolExecutionSummaries, options, } = args;
         const toolCallsForMessage = [];
         for (const [, t] of stepResult.toolCalls) {
             toolCallsForMessage.push({
@@ -708,14 +872,18 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
             }
             let output;
             let errorMsg;
-            const toolDef = toolsRecord[t.name];
+            // The model calls tools by their WIRE names; execution, events, and
+            // reporting use the registered names (reverse-mapped when a wire-name
+            // map is in effect — see buildWireToolNameMaps).
+            const registryName = toolNameFromWire?.get(t.name) ?? t.name;
+            const toolDef = toolsRecord[registryName];
             emitter?.emit("tool:start", {
-                toolName: t.name,
+                toolName: registryName,
                 toolCallId: t.id,
                 input,
             });
             if (!toolDef || typeof toolDef.execute !== "function") {
-                errorMsg = `Tool '${t.name}' is not registered.`;
+                errorMsg = `Tool '${registryName}' is not registered.`;
                 output = { error: errorMsg };
             }
             else {
@@ -728,10 +896,10 @@ export class OpenAIChatCompletionsProvider extends BaseProvider {
                 }
             }
             const endedAt = new Date();
-            toolsUsed.push(t.name);
+            toolsUsed.push(registryName);
             toolExecutionSummaries.push({
                 toolCallId: t.id,
-                toolName: t.name,
+                toolName: registryName,
                 input,
                 output,
                 ...(errorMsg ? { error: errorMsg } : {}),

package/dist/lib/providers/openaiChatCompletionsClient.d.ts

@@ -15,22 +15,40 @@
  */
 import type { OpenAICompatBuildBodyArgs, OpenAICompatChatMessage, OpenAICompatChatRequest, OpenAICompatChatTool, OpenAICompatMessage, OpenAICompatMessageContent, OpenAICompatResponseFormat, OpenAICompatSSEResult, OpenAICompatStreamChunk, OpenAICompatToolChoiceWire, OpenAICompatV3CallToolChoice, OpenAICompatV3CallTools, DeferredUsage, Tool } from "../types/index.js";
 export declare const stripTrailingSlash: (s: string) => string;
+/**
+ * Build a bijective original ↔ wire tool-name map. Returns undefined when
+ * every name is already wire-valid (the common case — the wire then uses
+ * original names untouched and callers skip all mapping). Sanitized names
+ * that collide get a deterministic numeric suffix so the map stays
+ * invertible.
+ */
+export declare const buildWireToolNameMaps: (names: readonly string[]) => {
+    toWire: Map<string, string>;
+    fromWire: Map<string, string>;
+} | undefined;
+/**
+ * Estimate the input-token cost of a fully-built wire request (messages +
+ * tool definitions). Used by the per-request max_tokens fit against a
+ * RUNTIME-DISCOVERED context window — deliberately the same char-based
+ * estimator the budget pipeline uses, so both layers agree.
+ */
+export declare const estimateWireTokens: (messages: ReadonlyArray<OpenAICompatChatMessage>, tools: OpenAICompatChatTool[] | undefined, provider?: string) => number;
 export declare const safeStringify: (value: unknown) => string;
 export declare const stringifyToolInput: (input: unknown) => string;
 export declare const stringifyToolOutput: (output: unknown) => string;
 export declare const imageDataToURL: (data: unknown) => string | undefined;
 export declare const convertContentForOpenAI: (content: unknown) => string | OpenAICompatMessageContent[];
-export declare const messageBuilderToOpenAI: (messages: ReadonlyArray<OpenAICompatMessage>) => OpenAICompatChatMessage[];
-export declare const buildToolsForOpenAI: (tools: Record<string, Tool>) => OpenAICompatChatTool[] | undefined;
-export declare const v3ToolsToOpenAI: (tools: OpenAICompatV3CallTools | undefined) => OpenAICompatChatTool[] | undefined;
-export declare const v3ToolChoiceToOpenAI: (choice: OpenAICompatV3CallToolChoice) => OpenAICompatToolChoiceWire | undefined;
+export declare const messageBuilderToOpenAI: (messages: ReadonlyArray<OpenAICompatMessage>, toolNameToWire?: Map<string, string>) => OpenAICompatChatMessage[];
+export declare const buildToolsForOpenAI: (tools: Record<string, Tool>, toolNameToWire?: Map<string, string>) => OpenAICompatChatTool[] | undefined;
+export declare const v3ToolsToOpenAI: (tools: OpenAICompatV3CallTools | undefined, toolNameToWire?: Map<string, string>) => OpenAICompatChatTool[] | undefined;
+export declare const v3ToolChoiceToOpenAI: (choice: OpenAICompatV3CallToolChoice, toolNameToWire?: Map<string, string>) => OpenAICompatToolChoiceWire | undefined;
 export declare const v3ResponseFormatToOpenAI: (rf: {
     type: "text" | "json";
     schema?: Record<string, unknown>;
     name?: string;
     description?: string;
 }) => OpenAICompatResponseFormat | undefined;
-export declare const mapNeuroLinkToolChoice: (choice: unknown) => OpenAICompatToolChoiceWire | undefined;
+export declare const mapNeuroLinkToolChoice: (choice: unknown, toolNameToWire?: Map<string, string>) => OpenAICompatToolChoiceWire | undefined;
 export declare const messagesContainJsonWord: (messages: ReadonlyArray<OpenAICompatChatMessage>) => boolean;
 export declare const ensureJsonWordInBody: (body: OpenAICompatChatRequest) => OpenAICompatChatRequest;
 export declare const requiresMaxCompletionTokens: (modelId: string) => boolean;

package/dist/lib/providers/openaiChatCompletionsClient.js

@@ -14,8 +14,72 @@
  * module is to be the native replacement for the AI SDK's OpenAI wrapper.
  */
 import { createParser } from "eventsource-parser";
-import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
+import { sanitizeToolName } from "../mcp/toolConverter.js";
+import { convertZodToJsonSchema, normalizeWireToolSchema, } from "../utils/schemaConversion.js";
+import { estimateTokens, TOKENS_PER_MESSAGE, } from "../utils/tokenEstimation.js";
 export const stripTrailingSlash = (s) => s.replace(/\/+$/, "");
+// OpenAI-compatible wire tool names: first char letter/underscore (some
+// chat templates treat a leading digit or hyphen as invalid identifiers),
+// then letters/digits/underscore/hyphen, 64 chars total — exactly the
+// pattern below, which mirrors sanitizeToolName's output alphabet. MCP
+// servers can register names outside it (dots, colons, spaces); sent
+// verbatim they make backends reject the tools block or emit tool_calls
+// that no longer match the registry.
+const WIRE_TOOL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$/;
+/**
+ * Build a bijective original ↔ wire tool-name map. Returns undefined when
+ * every name is already wire-valid (the common case — the wire then uses
+ * original names untouched and callers skip all mapping). Sanitized names
+ * that collide get a deterministic numeric suffix so the map stays
+ * invertible.
+ */
+export const buildWireToolNameMaps = (names) => {
+    if (names.every((name) => WIRE_TOOL_NAME_RE.test(name))) {
+        return undefined;
+    }
+    const toWire = new Map();
+    const fromWire = new Map();
+    for (const name of names) {
+        let wire = WIRE_TOOL_NAME_RE.test(name) ? name : sanitizeToolName(name);
+        if (fromWire.has(wire)) {
+            let suffix = 2;
+            let candidate;
+            do {
+                const tail = `_${suffix}`;
+                candidate = `${wire.slice(0, 64 - tail.length)}${tail}`;
+                suffix++;
+            } while (fromWire.has(candidate));
+            wire = candidate;
+        }
+        toWire.set(name, wire);
+        fromWire.set(wire, name);
+    }
+    return { toWire, fromWire };
+};
+/**
+ * Estimate the input-token cost of a fully-built wire request (messages +
+ * tool definitions). Used by the per-request max_tokens fit against a
+ * RUNTIME-DISCOVERED context window — deliberately the same char-based
+ * estimator the budget pipeline uses, so both layers agree.
+ */
+export const estimateWireTokens = (messages, tools, provider) => {
+    let total = 0;
+    for (const message of messages) {
+        const content = typeof message.content === "string"
+            ? message.content
+            : safeStringify(message.content);
+        total += estimateTokens(content, provider) + TOKENS_PER_MESSAGE;
+        // tool_calls only exists on the assistant variant of the message union.
+        const toolCalls = message.tool_calls;
+        if (toolCalls) {
+            total += estimateTokens(safeStringify(toolCalls), provider);
+        }
+    }
+    if (tools && tools.length > 0) {
+        total += estimateTokens(safeStringify(tools), provider);
+    }
+    return total;
+};
 export const safeStringify = (value) => {
     try {
         return JSON.stringify(value ?? "");
@@ -132,7 +196,7 @@ export const convertContentForOpenAI = (content) => {
     }
     return out;
 };
-export const messageBuilderToOpenAI = (messages) => {
+export const messageBuilderToOpenAI = (messages, toolNameToWire) => {
     const out = [];
     for (const msg of messages) {
         switch (msg.role) {
@@ -165,11 +229,14 @@ export const messageBuilderToOpenAI = (messages) => {
                         }
                         else if (p.type === "tool-call") {
                             const tc = part;
+                            // History tool-call names must match the wire `tools` block —
+                            // forward-map when a wire-name map is in effect.
+                            const historyName = tc.toolName ?? "";
                             toolCalls.push({
                                 id: tc.toolCallId ?? "",
                                 type: "function",
                                 function: {
-                                    name: tc.toolName ?? "",
+                                    name: toolNameToWire?.get(historyName) ?? historyName,
                                     arguments: stringifyToolInput(tc.input),
                                 },
                             });
@@ -223,7 +290,7 @@ export const messageBuilderToOpenAI = (messages) => {
     }
     return out;
 };
-export const buildToolsForOpenAI = (tools) => {
+export const buildToolsForOpenAI = (tools, toolNameToWire) => {
     const entries = Object.entries(tools);
     if (entries.length === 0) {
         return undefined;
@@ -235,14 +302,16 @@ export const buildToolsForOpenAI = (tools) => {
         // tool.inputSchema may be a Zod schema, an AI SDK jsonSchema() wrapper,
         // or plain JSON Schema — convertZodToJsonSchema normalizes all three.
         // Sending raw Zod internals (with `_def`) gets rejected by most
-        // OpenAI-compatible endpoints.
+        // OpenAI-compatible endpoints. normalizeWireToolSchema then strips
+        // $schema/$defs indirection that proxied backends render into chat
+        // templates verbatim (degrading argument generation).
         const parameters = rawSchema
-            ? convertZodToJsonSchema(rawSchema)
+            ? normalizeWireToolSchema(convertZodToJsonSchema(rawSchema))
             : { type: "object", properties: {} };
         out.push({
             type: "function",
             function: {
-                name,
+                name: toolNameToWire?.get(name) ?? name,
                 ...(t.description ? { description: t.description } : {}),
                 parameters,
             },
@@ -254,7 +323,7 @@ export const buildToolsForOpenAI = (tools) => {
 // path that BaseProvider's `generate()` still drives via the AI SDK's
 // `generateText`. The streaming path doesn't need these — it consumes
 // NeuroLink-shaped options directly.
-export const v3ToolsToOpenAI = (tools) => {
+export const v3ToolsToOpenAI = (tools, toolNameToWire) => {
     if (!tools || tools.length === 0) {
         return undefined;
     }
@@ -264,9 +333,12 @@ export const v3ToolsToOpenAI = (tools) => {
             out.push({
                 type: "function",
                 function: {
-                    name: t.name,
+                    name: toolNameToWire?.get(t.name) ?? t.name,
                     ...(t.description ? { description: t.description } : {}),
-                    parameters: t.inputSchema,
+                    // The AI SDK serializes inputSchema to JSON Schema before
+                    // doGenerate; normalize the wire form ($ref/$defs inlining,
+                    // annotation stripping, nullable collapse) for proxied backends.
+                    parameters: normalizeWireToolSchema(t.inputSchema),
                     ...(t.strict !== undefined ? { strict: t.strict } : {}),
                 },
             });
@@ -276,14 +348,19 @@ export const v3ToolsToOpenAI = (tools) => {
     }
     return out.length > 0 ? out : undefined;
 };
-export const v3ToolChoiceToOpenAI = (choice) => {
+export const v3ToolChoiceToOpenAI = (choice, toolNameToWire) => {
     switch (choice.type) {
         case "auto":
         case "none":
         case "required":
             return choice.type;
         case "tool":
-            return { type: "function", function: { name: choice.toolName } };
+            return {
+                type: "function",
+                function: {
+                    name: toolNameToWire?.get(choice.toolName) ?? choice.toolName,
+                },
+            };
     }
 };
 export const v3ResponseFormatToOpenAI = (rf) => {
@@ -303,7 +380,7 @@ export const v3ResponseFormatToOpenAI = (rf) => {
         },
     };
 };
-export const mapNeuroLinkToolChoice = (choice) => {
+export const mapNeuroLinkToolChoice = (choice, toolNameToWire) => {
     if (!choice) {
         return undefined;
     }
@@ -313,7 +390,10 @@ export const mapNeuroLinkToolChoice = (choice) => {
     if (typeof choice === "object" && choice !== null) {
         const c = choice;
         if (c.type === "tool" && c.toolName) {
-            return { type: "function", function: { name: c.toolName } };
+            return {
+                type: "function",
+                function: { name: toolNameToWire?.get(c.toolName) ?? c.toolName },
+            };
         }
     }
     return undefined;