@juspay/neurolink 10.2.2 → 10.3.1

package/dist/proxy/proxyFetch.d.ts

@@ -3,6 +3,23 @@
  * Supports HTTP/HTTPS, SOCKS4/5, authentication, and NO_PROXY bypass
  * Lightweight implementation extracted from research of major proxy packages
  */
+/**
+ * Classify a fetch failure as a transient network error worth retrying.
+ *
+ * undici's `fetch()` wraps the real failure in `TypeError: fetch failed`
+ * with the actionable code (`ECONNRESET`, `UND_ERR_SOCKET`, ...) on
+ * `error.cause` — sometimes nested another level (e.g. SocketError inside
+ * a ConnectTimeoutError). Walk the cause chain so those are recognized;
+ * checking only the top-level error silently classified every undici
+ * connection death as non-retryable.
+ *
+ * Deliberately NOT retried: `UND_ERR_HEADERS_TIMEOUT` / `UND_ERR_BODY_TIMEOUT`
+ * — those already waited out undici's own long deadline (default 300s), and
+ * replaying them can triple a stall under the caller's wall-clock budget.
+ *
+ * Exported for direct coverage by the no-API test suite.
+ */
+export declare function isTransientNetworkError(error: unknown): boolean;
 /**
  * Create a proxy-aware fetch function with enhanced capabilities
  * Supports HTTP/HTTPS, SOCKS4/5, authentication, and NO_PROXY bypass

package/dist/proxy/proxyFetch.js

@@ -79,6 +79,47 @@ function extractHostname(url) {
         return "[unknown]";
     }
 }
+/** Error codes classified as transient (module-scope: the retry path is hot). */
+const TRANSIENT_NETWORK_CODES = new Set([
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ECONNREFUSED",
+    "EPIPE",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+/**
+ * Classify a fetch failure as a transient network error worth retrying.
+ *
+ * undici's `fetch()` wraps the real failure in `TypeError: fetch failed`
+ * with the actionable code (`ECONNRESET`, `UND_ERR_SOCKET`, ...) on
+ * `error.cause` — sometimes nested another level (e.g. SocketError inside
+ * a ConnectTimeoutError). Walk the cause chain so those are recognized;
+ * checking only the top-level error silently classified every undici
+ * connection death as non-retryable.
+ *
+ * Deliberately NOT retried: `UND_ERR_HEADERS_TIMEOUT` / `UND_ERR_BODY_TIMEOUT`
+ * — those already waited out undici's own long deadline (default 300s), and
+ * replaying them can triple a stall under the caller's wall-clock budget.
+ *
+ * Exported for direct coverage by the no-API test suite.
+ */
+export function isTransientNetworkError(error) {
+    let current = error;
+    for (let depth = 0; depth < 5 && current; depth++) {
+        const err = current;
+        if (err.code && TRANSIENT_NETWORK_CODES.has(err.code)) {
+            return true;
+        }
+        if (err.message?.includes("socket hang up") ||
+            err.message?.includes("network socket disconnected") ||
+            err.message?.includes("other side closed")) {
+            return true;
+        }
+        current = err.cause;
+    }
+    return false;
+}
 /**
  * Retry-aware fetch wrapper for transient network errors (ECONNRESET, ETIMEDOUT, socket hang up).
  * Protects all LLM API calls and token refreshes that go through createProxyFetch().
@@ -104,11 +145,8 @@ async function fetchWithRetry(url, init, maxRetries = 3, baseDelay = 500) {
                     return response;
                 }
                 catch (error) {
+                    const isRetryable = isTransientNetworkError(error);
                     const err = error;
-                    const isRetryable = err?.code === "ECONNRESET" ||
-                        err?.code === "ETIMEDOUT" ||
-                        err?.message?.includes("socket hang up") ||
-                        err?.message?.includes("network socket disconnected");
                     if (!isRetryable || attempt === maxRetries) {
                         // Final failure — record on span and rethrow
                         span.setAttribute("http.request.total_attempts", totalAttempts);

package/dist/types/context.d.ts

@@ -219,6 +219,28 @@ export type BudgetCheckResult = {
         fileAttachments: number;
     };
 };
+/**
+ * Configuration for the per-step context budget guard that compacts the
+ * AI-SDK tool loop's messages before they overflow the model window
+ * (context/stepBudgetGuard.ts).
+ */
+export type StepBudgetGuardConfig = {
+    provider: string;
+    model?: string;
+    /** The caller's requested output budget (reserved out of the window). */
+    maxTokens?: number;
+    /** Static token cost of the hoisted system prompt + tool definitions. */
+    fixedOverheadTokens?: number;
+    /**
+     * Dynamic overhead resolver, re-evaluated on EVERY guard invocation. Takes
+     * precedence over `fixedOverheadTokens`. Use when the tool set can grow
+     * mid-loop (search_tools hydration) so newly added definitions count toward
+     * the budget.
+     */
+    getFixedOverheadTokens?: () => number;
+    /** Override the trigger ratio; defaults to DEFAULT_CONTEXT_GUARD_RATIO. */
+    thresholdRatio?: number;
+};
 /** Parameters for budget checking. */
 export type BudgetCheckParams = {
     provider: string;

package/dist/types/generate.d.ts

@@ -323,8 +323,15 @@ export type GenerateOptions = {
      * never the step-cap text. Unset = no turn-level deadline (the library
      * imposes no product policy).
      *
-     * Enforced by the native Vertex loops (Gemini + Claude); AI-SDK-driven
-     * providers currently ignore it.
+     * Enforced by the native Vertex loops (Gemini + Claude) AND the AI-SDK
+     * loop path (litellm and other OpenAI-compatible providers). On the AI-SDK
+     * path, an explicit `timeout` also engages the same wrap-up when
+     * `turnTimeoutMs` is unset. Once the wrap-up window begins (see
+     * `wrapupTimeLeadMs`), the loop forcibly sets `toolChoice: "none"` for the
+     * remaining steps — overriding any caller-supplied `toolChoice` or
+     * `prepareStep` tool selection — and appends an honest time message that a
+     * caller's `prepareStep` callback does not observe (it runs before the
+     * wrap-up nudge is applied). An honest partial beats a discarded turn.
      */
     turnTimeoutMs?: number;
     /**
@@ -340,6 +347,11 @@ export type GenerateOptions = {
      * next tool-result turn telling the model to consolidate what it has and
      * produce its final answer. Defaults to 120_000 when `turnTimeoutMs` is
      * set; ignored when it is not.
+     *
+     * On the AI-SDK loop path the lead is clamped to a quarter of the turn
+     * budget (so short budgets don't wrap up on step one) and wrap-up steps
+     * run with a forced `toolChoice: "none"` — see `turnTimeoutMs` for the
+     * exact override semantics.
      */
     wrapupTimeLeadMs?: number;
     /**
@@ -350,6 +362,8 @@ export type GenerateOptions = {
     toolTimeoutMs?: number;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
+    /** Disable the schema-driven tool call repair mechanism (BZ-665). Default: false (repair enabled). */
+    disableToolCallRepair?: boolean;
     /**
      * Disable tool execution (including built-in tools)
      *
@@ -1015,6 +1029,8 @@ export type TextGenerationOptions = {
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     disableTools?: boolean;
+    /** Disable the schema-driven tool call repair mechanism (BZ-665). Default: false (repair enabled). */
+    disableToolCallRepair?: boolean;
     maxSteps?: number;
     /** Include only these tools by name (whitelist). If set, only matching tools are available. */
     toolFilter?: string[];

package/dist/types/openaiCompatible.d.ts

@@ -226,6 +226,8 @@ export type StreamLoopArgs = {
     openAITools: OpenAICompatChatTool[] | undefined;
     openAIToolChoice: OpenAICompatToolChoiceWire | undefined;
     toolsRecord: Record<string, Tool>;
+    /** Wire → registered tool-name map when sanitization was needed (see buildWireToolNameMaps). */
+    toolNameFromWire?: Map<string, string>;
     emitter: TypedEventEmitter<NeuroLinkEvents> | undefined;
     toolsUsed: string[];
     toolExecutionSummaries: ToolExecutionSummaryInternal[];

package/dist/types/providers.d.ts

@@ -601,6 +601,15 @@ export type AIProvider = {
      * external AIProvider implementations — callers treat absence as `true`.
      */
     supportsTools?(): boolean;
+    /**
+     * Ensure runtime-discovered model limits (context window, output-token
+     * ceiling) are registered before budget math runs. Implemented by
+     * BaseProvider (default no-op); providers with a discovery source override
+     * it (LiteLLM `/model/info`). Must never reject — discovery failure
+     * degrades to static defaults. Optional for compile compatibility with
+     * external AIProvider implementations — callers treat absence as no-op.
+     */
+    ensureModelLimits?(): Promise<void>;
 };
 /**
  * Provider attempt result for iteration tracking (converted from interface)

package/dist/utils/errorHandling.js

@@ -1012,12 +1012,18 @@ export class ErrorFactory {
  * Timeout wrapper for async operations
  */
 export async function withTimeout(promise, timeoutMs, timeoutError) {
+    let timer;
     const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => {
+        timer = setTimeout(() => {
             reject(timeoutError || new Error(`Operation timed out after ${timeoutMs}ms`));
         }, timeoutMs);
     });
-    return Promise.race([promise, timeoutPromise]);
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
 }
 /**
  * Retry mechanism for retriable operations

package/dist/utils/schemaConversion.d.ts

@@ -29,6 +29,22 @@ export declare function ensureNestedSchemaTypes(schema: Record<string, unknown>)
  */
 export declare function convertZodToJsonSchema(zodSchema: ZodUnknownSchema, target?: "jsonSchema7" | "openApi3"): object;
 export declare function normalizeJsonSchemaObject(schema: Record<string, unknown> | undefined | null): Record<string, unknown>;
+/**
+ * Normalize a JSON Schema for the OpenAI chat-completions `tools` wire
+ * block. Generic proxied backends (LiteLLM → vllm/GLM/Qwen, local servers)
+ * render tool schemas into chat templates more or less verbatim, so `$ref`
+ * indirection, `$defs` containers, `$schema` annotations, and zod's
+ * nullable `anyOf` pattern all measurably degrade argument generation —
+ * this is the parity gap behind "the model can't find the right arguments"
+ * on litellm while the same tools work on Gemini/Claude native paths
+ * (which sanitize schemas before the wire).
+ *
+ * Pipeline: strip annotation keys → inline local `$ref`/`$defs`/
+ * `definitions` → collapse nullable variants → guarantee a top-level object
+ * shape. Identity for already-clean schemas; `description`, `required`,
+ * `enum`, and `default` — what models actually read — are always preserved.
+ */
+export declare function normalizeWireToolSchema(schema: unknown): Record<string, unknown>;
 /**
  * Check if a value is a Zod schema
  */

package/dist/utils/schemaConversion.js

@@ -80,9 +80,11 @@ function safePercentDecode(segment) {
  * - Circular reference detection to prevent infinite loops
  */
 export function inlineJsonSchema(schema, definitions, visited = new Set(), rootSchema) {
-    // Use definitions from schema if not provided
+    // Use definitions from schema if not provided. Modern MCP servers and
+    // zod v4's native toJSONSchema emit the 2020-12 `$defs` keyword; older
+    // emitters use draft-07 `definitions`. Support both.
     const defs = definitions ||
-        schema.definitions;
+        (schema.definitions ?? schema.$defs);
     // Keep track of the root schema for deep ref resolution
     const root = rootSchema || schema;
     // Handle $ref at current level
@@ -94,10 +96,14 @@ export function inlineJsonSchema(schema, definitions, visited = new Set(), rootS
             // Return a simple object placeholder for circular refs
             return { type: "object" };
         }
-        // Try simple definition lookup first (for #/definitions/SomeName)
-        if (refPath.startsWith("#/definitions/")) {
-            const defName = refPath.replace("#/definitions/", "");
-            // Check if it's a simple definition name (no slashes after definitions/)
+        // Try simple definition lookup first (#/definitions/SomeName or the
+        // 2020-12 #/$defs/SomeName form)
+        if (refPath.startsWith("#/definitions/") ||
+            refPath.startsWith("#/$defs/")) {
+            const defName = refPath
+                .replace("#/definitions/", "")
+                .replace("#/$defs/", "");
+            // Check if it's a simple definition name (no slashes after the prefix)
             if (!defName.includes("/") && defs && defs[defName]) {
                 visited.add(refPath);
                 const resolved = inlineJsonSchema({ ...defs[defName] }, defs, visited, root);
@@ -124,8 +130,8 @@ export function inlineJsonSchema(schema, definitions, visited = new Set(), rootS
     // Create result without $ref and definitions
     const result = {};
     for (const [key, value] of Object.entries(schema)) {
-        // Skip $ref and definitions keys
-        if (key === "$ref" || key === "definitions") {
+        // Skip $ref and definition-container keys (both draft-07 and 2020-12)
+        if (key === "$ref" || key === "definitions" || key === "$defs") {
             continue;
         }
         // Recursively process nested schemas
@@ -402,6 +408,157 @@ function ensureTypeField(schema) {
     }
     return schema;
 }
+/** JSON Schema keys whose values are themselves schemas (single). */
+const SCHEMA_VALUE_KEYS = new Set([
+    "items",
+    "additionalProperties",
+    "not",
+    "if",
+    "then",
+    "else",
+    "contains",
+    "propertyNames",
+]);
+/** JSON Schema keys whose values are arrays of schemas. */
+const SCHEMA_ARRAY_KEYS = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+/** JSON Schema keys whose values are name → schema maps. */
+const SCHEMA_MAP_KEYS = new Set([
+    "properties",
+    "patternProperties",
+    "$defs",
+    "definitions",
+]);
+/**
+ * Annotation keys that carry no validation semantics for a model and that
+ * generic OpenAI-compatible backends (vllm, GLM/Qwen chat templates, local
+ * servers) may render into the prompt verbatim, confusing argument
+ * generation. Removed only at SCHEMA positions — never inside data values
+ * like `default`, `const`, `enum` or `examples`, where `$id` etc. are
+ * legitimate payload.
+ */
+const SCHEMA_ANNOTATION_KEYS = new Set(["$schema", "$id", "$comment"]);
+/** Walk schema positions only, dropping annotation-only keys. */
+function stripSchemaAnnotations(schema) {
+    const result = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (SCHEMA_ANNOTATION_KEYS.has(key)) {
+            continue;
+        }
+        if (SCHEMA_VALUE_KEYS.has(key) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            result[key] = stripSchemaAnnotations(value);
+        }
+        else if (SCHEMA_ARRAY_KEYS.has(key) && Array.isArray(value)) {
+            result[key] = value.map((item) => item && typeof item === "object" && !Array.isArray(item)
+                ? stripSchemaAnnotations(item)
+                : item);
+        }
+        else if (SCHEMA_MAP_KEYS.has(key) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            const map = {};
+            for (const [name, sub] of Object.entries(value)) {
+                map[name] =
+                    sub && typeof sub === "object" && !Array.isArray(sub)
+                        ? stripSchemaAnnotations(sub)
+                        : sub;
+            }
+            result[key] = map;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Collapse the zod-emitted nullable pattern `anyOf/oneOf: [T, {type:"null"}]`
+ * into `{...T, type: [t, "null"]}`. Weaker OSS models handle a plain type
+ * array far better than composition keywords when choosing tool arguments.
+ * Conservative: only fires for exactly-two variants where the non-null
+ * variant has a primitive `type` string — everything else passes through.
+ */
+function collapseNullableVariants(schema) {
+    const result = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (SCHEMA_VALUE_KEYS.has(key) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            result[key] = collapseNullableVariants(value);
+        }
+        else if (SCHEMA_ARRAY_KEYS.has(key) && Array.isArray(value)) {
+            result[key] = value.map((item) => item && typeof item === "object" && !Array.isArray(item)
+                ? collapseNullableVariants(item)
+                : item);
+        }
+        else if (SCHEMA_MAP_KEYS.has(key) &&
+            value &&
+            typeof value === "object" &&
+            !Array.isArray(value)) {
+            const map = {};
+            for (const [name, sub] of Object.entries(value)) {
+                map[name] =
+                    sub && typeof sub === "object" && !Array.isArray(sub)
+                        ? collapseNullableVariants(sub)
+                        : sub;
+            }
+            result[key] = map;
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    for (const compositionKey of ["anyOf", "oneOf"]) {
+        const variants = result[compositionKey];
+        if (!Array.isArray(variants) || variants.length !== 2) {
+            continue;
+        }
+        const isNullVariant = (v) => !!v &&
+            typeof v === "object" &&
+            v.type === "null";
+        const nullIndex = variants.findIndex(isNullVariant);
+        if (nullIndex === -1) {
+            continue;
+        }
+        const other = variants[1 - nullIndex];
+        if (!other ||
+            typeof other !== "object" ||
+            Array.isArray(other) ||
+            typeof other.type !== "string" ||
+            other.type === "null") {
+            continue;
+        }
+        // Merge: variant content + outer annotations (description etc.) win.
+        const { [compositionKey]: _dropped, ...outer } = result;
+        return { ...other, ...outer, type: [other.type, "null"] };
+    }
+    return result;
+}
+/**
+ * Normalize a JSON Schema for the OpenAI chat-completions `tools` wire
+ * block. Generic proxied backends (LiteLLM → vllm/GLM/Qwen, local servers)
+ * render tool schemas into chat templates more or less verbatim, so `$ref`
+ * indirection, `$defs` containers, `$schema` annotations, and zod's
+ * nullable `anyOf` pattern all measurably degrade argument generation —
+ * this is the parity gap behind "the model can't find the right arguments"
+ * on litellm while the same tools work on Gemini/Claude native paths
+ * (which sanitize schemas before the wire).
+ *
+ * Pipeline: strip annotation keys → inline local `$ref`/`$defs`/
+ * `definitions` → collapse nullable variants → guarantee a top-level object
+ * shape. Identity for already-clean schemas; `description`, `required`,
+ * `enum`, and `default` — what models actually read — are always preserved.
+ */
+export function normalizeWireToolSchema(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+        return { type: "object", properties: {} };
+    }
+    return ensureTypeField(collapseNullableVariants(inlineJsonSchema(stripSchemaAnnotations(schema))));
+}
 /**
  * Check if a value is a Zod schema
  */

package/dist/utils/timeout.d.ts

@@ -128,8 +128,30 @@ export declare function createTimeoutController(timeout: number | string | undef
  * @returns Combined AbortSignal, or undefined if neither is present
  */
 export declare function composeAbortSignals(externalSignal?: AbortSignal, timeoutSignal?: AbortSignal): AbortSignal | undefined;
+/**
+ * Scoped variant of {@link composeAbortSignals} for per-step / per-request
+ * composition against a LONG-LIVED external signal (e.g. the generate-call
+ * signal inside a multi-step agent loop). `AbortSignal.any` keeps its source
+ * registration alive until the derived signal is GC'd, so composing per step
+ * accumulates listeners on the outer signal for the whole turn
+ * (MaxListenersExceededWarning at 10+ steps). This helper registers plain
+ * listeners instead and returns a `dispose()` that removes them the moment
+ * the step settles.
+ */
+export declare function composeAbortSignalsScoped(externalSignal?: AbortSignal, timeoutSignal?: AbortSignal): {
+    signal: AbortSignal | undefined;
+    dispose: () => void;
+};
 /**
  * Merge abort signals (for combining user abort with timeout)
+ *
+ * Implemented via `AbortSignal.any` with a single once-listener forward, so
+ * no per-source listeners are left behind on long-lived input signals once
+ * the merged controller becomes unreachable (registrations are released with
+ * the derived signal). The previous implementation attached one permanent
+ * listener per source per call — repeated stream calls sharing one caller
+ * signal accumulated listeners for the life of that signal.
+ *
  * @param signals - Array of abort signals to merge
  * @returns Combined abort controller
  */

package/dist/utils/timeout.js

@@ -342,25 +342,85 @@ export function composeAbortSignals(externalSignal, timeoutSignal) {
     }
     return externalSignal ?? timeoutSignal;
 }
+/**
+ * Scoped variant of {@link composeAbortSignals} for per-step / per-request
+ * composition against a LONG-LIVED external signal (e.g. the generate-call
+ * signal inside a multi-step agent loop). `AbortSignal.any` keeps its source
+ * registration alive until the derived signal is GC'd, so composing per step
+ * accumulates listeners on the outer signal for the whole turn
+ * (MaxListenersExceededWarning at 10+ steps). This helper registers plain
+ * listeners instead and returns a `dispose()` that removes them the moment
+ * the step settles.
+ */
+export function composeAbortSignalsScoped(externalSignal, timeoutSignal) {
+    if (!externalSignal || !timeoutSignal) {
+        return { signal: externalSignal ?? timeoutSignal, dispose: () => { } };
+    }
+    const controller = new AbortController();
+    const sources = [externalSignal, timeoutSignal];
+    const listeners = [];
+    const dispose = () => {
+        for (const { source, listener } of listeners) {
+            source.removeEventListener("abort", listener);
+        }
+        listeners.length = 0;
+    };
+    const onAbort = (source) => {
+        if (!controller.signal.aborted) {
+            controller.abort(source.reason);
+        }
+        // Self-clean on abort: once the composed signal fired, no source
+        // listener has any work left — detach from the OTHER source too (the
+        // firing one auto-removed via `once`), so callers that only observe
+        // `signal.aborted` and never reach their dispose() leave nothing behind.
+        dispose();
+    };
+    for (const source of sources) {
+        const listener = () => onAbort(source);
+        source.addEventListener("abort", listener, { once: true });
+        listeners.push({ source, listener });
+    }
+    for (const source of sources) {
+        if (source.aborted) {
+            onAbort(source);
+            break;
+        }
+    }
+    return { signal: controller.signal, dispose };
+}
 /**
  * Merge abort signals (for combining user abort with timeout)
+ *
+ * Implemented via `AbortSignal.any` with a single once-listener forward, so
+ * no per-source listeners are left behind on long-lived input signals once
+ * the merged controller becomes unreachable (registrations are released with
+ * the derived signal). The previous implementation attached one permanent
+ * listener per source per call — repeated stream calls sharing one caller
+ * signal accumulated listeners for the life of that signal.
+ *
  * @param signals - Array of abort signals to merge
  * @returns Combined abort controller
  */
 export function mergeAbortSignals(signals) {
     const controller = new AbortController();
-    for (const signal of signals) {
-        if (signal && !signal.aborted) {
-            signal.addEventListener("abort", () => {
-                if (!controller.signal.aborted) {
-                    controller.abort(signal.reason);
-                }
-            });
-        }
-        if (signal?.aborted) {
-            controller.abort(signal.reason);
-            break;
-        }
+    const active = signals.filter((s) => s !== undefined);
+    const aborted = active.find((s) => s.aborted);
+    if (aborted) {
+        controller.abort(aborted.reason);
+        return controller;
     }
+    if (active.length === 0) {
+        return controller;
+    }
+    const merged = AbortSignal.any(active);
+    merged.addEventListener("abort", () => {
+        if (!controller.signal.aborted) {
+            controller.abort(merged.reason);
+        }
+    }, { once: true });
+    // Pin the derived signal to the returned controller: sources hold only
+    // weak refs to `any()` dependents, so without this strong ref the derived
+    // signal (and the forward listener with it) could be GC'd before firing.
+    controller.__nlMergedSignal = merged;
     return controller;
 }

package/dist/utils/tokenLimits.js

@@ -2,6 +2,7 @@
  * Provider-specific token limit utilities
  * Provides safe maxTokens values based on provider and model capabilities
  */
+import { getRuntimeOutputCeiling } from "../constants/contextWindows.js";
 import { PROVIDER_MAX_TOKENS } from "../core/constants.js";
 import { logger } from "./logger.js";
 import { hasRestrictedOutputLimit, RESTRICTED_OUTPUT_TOKEN_LIMIT, } from "./modelDetection.js";
@@ -34,6 +35,27 @@ export function getSafeMaxTokens(provider, model, requestedMaxTokens) {
         // Otherwise, use the requested value (it's within limits, including 0)
         return requestedMaxTokens;
     }
+    // Runtime-discovered output ceiling (e.g. LiteLLM /model/info
+    // max_output_tokens): the serving infrastructure's own number for the
+    // deployed model, authoritative over the static per-provider table. This
+    // both clamps over-large requests to the real cap AND replaces the static
+    // provider default for callers that pass no maxTokens — the litellm
+    // blanket default (128000) is a context-window-sized value that slashed
+    // usable input on total-context backends. Checked AFTER the
+    // restricted-model branch so hard caps proven at the origin API (Gemini 3
+    // / image models) still win over a proxy that over-advertises them.
+    const runtimeCeiling = getRuntimeOutputCeiling(provider, model);
+    if (runtimeCeiling !== undefined) {
+        if (requestedMaxTokens === undefined || requestedMaxTokens === null) {
+            return runtimeCeiling;
+        }
+        if (requestedMaxTokens > runtimeCeiling) {
+            logger.warn(`Requested maxTokens ${requestedMaxTokens} exceeds the advertised ` +
+                `${provider}/${model} output ceiling of ${runtimeCeiling}. Using ${runtimeCeiling} instead.`);
+            return runtimeCeiling;
+        }
+        return requestedMaxTokens;
+    }
     // Get provider-specific limits
     const providerLimits = PROVIDER_MAX_TOKENS[provider];
     if (!providerLimits) {

package/dist/utils/toolCallRepair.d.ts

@@ -4,3 +4,11 @@ import type { ToolCallRepairFunction, ToolSet } from "../types/index.js";
  * Fully dynamic — reads the tool schema at repair time, no configuration needed.
  */
 export declare function createToolCallRepair(): ToolCallRepairFunction<ToolSet>;
+/**
+ * Coerce a value to match the expected schema type.
+ * Handles: string→number, JSON string→object, JSON string→array, value→[value].
+ * Exported for reuse by the MCP-layer parameter validator
+ * (toolDiscoveryService), which coerces before rejecting so a recoverable
+ * mismatch doesn't cost the agent loop a full model round-trip.
+ */
+export declare function coerceType(value: unknown, propSchema: Record<string, unknown>): unknown;

package/dist/utils/toolCallRepair.js

@@ -173,8 +173,11 @@ function findMatchingKey(inputKey, schemaKeys) {
 /**
  * Coerce a value to match the expected schema type.
  * Handles: string→number, JSON string→object, JSON string→array, value→[value].
+ * Exported for reuse by the MCP-layer parameter validator
+ * (toolDiscoveryService), which coerces before rejecting so a recoverable
+ * mismatch doesn't cost the agent loop a full model round-trip.
  */
-function coerceType(value, propSchema) {
+export function coerceType(value, propSchema) {
     const expectedType = propSchema.type;
     if (!expectedType || value === null || value === undefined) {
         return value;