@juspay/neurolink 10.3.0 → 10.4.0

package/dist/lib/context/stepBudgetGuard.js

@@ -37,6 +37,13 @@ import { generateToolOutputPreview } from "./toolOutputLimits.js";
 import { logger } from "../utils/logger.js";
 /** Estimated tokens for a tool definition that fails to serialize. */
 const TOKENS_PER_TOOL_DEFINITION = 200;
+/**
+ * Upper bound on the usage-feedback calibration ratio. Real tokenizers count
+ * dense code/diff content at up to ~1.3× the char-based estimate; anything
+ * far beyond that indicates inconsistent provider usage reporting, and an
+ * unbounded ratio would compact the loop into uselessness.
+ */
+const MAX_CALIBRATION_RATIO = 3;
 /** Messages at the end of the conversation the guard never modifies. */
 const PROTECTED_TAIL_MESSAGES = 4;
 /** Stage-1 preview budget for an old tool output (bytes). */
@@ -230,19 +237,45 @@ function dropOldestToolExchanges(messages, budgetTokens, fixedOverheadTokens, pr
 }
 /**
  * Create a per-step budget guard. Returns a function that, given the step's
- * messages, returns a compacted replacement array when the projected request
- * exceeds the threshold — or `undefined` when no change is needed.
+ * messages (and optionally the REAL input-token count the provider reported
+ * for the previous step), returns a compacted replacement array when the
+ * projected request exceeds the threshold — or `undefined` when no change is
+ * needed.
+ *
+ * Two dynamic behaviours:
+ *  - the available-input budget is re-resolved on EVERY invocation, so
+ *    runtime window discovery (`/model/info`, overflow self-healing) that
+ *    lands mid-loop takes effect immediately instead of the guard staying
+ *    frozen on the value captured at loop start;
+ *  - usage feedback calibrates the estimator: the ratio between the real
+ *    prompt tokens of the previous step and this guard's own estimate for
+ *    what that step sent scales later estimates (only UP — underestimates
+ *    overflow, overestimates merely compact earlier), eliminating the
+ *    char-based estimator's drift on dense code/diff content without
+ *    shipping a tokenizer.
  */
 export function createStepBudgetGuard(config) {
     const { provider, model, maxTokens, fixedOverheadTokens = 0, getFixedOverheadTokens, thresholdRatio = DEFAULT_CONTEXT_GUARD_RATIO, } = config;
-    const availableInput = getAvailableInputTokens(provider, model, maxTokens);
-    const thresholdTokens = Math.floor(availableInput * thresholdRatio);
-    return function guardStepMessages(messages) {
+    // Calibration state: raw estimate for the messages the PREVIOUS guard
+    // invocation let through (what was actually sent), and the current ratio.
+    let lastRawEstimate = 0;
+    let calibration = 1;
+    return function guardStepMessages(messages, observedInputTokensLastStep) {
+        const availableInput = getAvailableInputTokens(provider, model, maxTokens);
+        const thresholdTokens = Math.floor(availableInput * thresholdRatio);
         // Resolve overhead per invocation: the tool set can GROW mid-loop
         // (search_tools hydration adds discovered tools between steps), so a
         // once-captured value would undercount later steps.
         const overheadTokens = getFixedOverheadTokens?.() ?? fixedOverheadTokens;
-        const estimate = overheadTokens + estimateStepMessagesTokens(messages, provider);
+        const rawEstimate = overheadTokens + estimateStepMessagesTokens(messages, provider);
+        if (observedInputTokensLastStep !== undefined &&
+            observedInputTokensLastStep > 0 &&
+            lastRawEstimate > 0) {
+            calibration = Math.min(MAX_CALIBRATION_RATIO, Math.max(1, observedInputTokensLastStep / lastRawEstimate));
+        }
+        // Apply calibration to the THRESHOLD instead of every estimate so the
+        // compaction stages keep operating on raw numbers.
+        const effectiveThreshold = Math.floor(thresholdTokens / calibration);
         // Logger Guard: per-step diagnostics for debugging why a long run does
         // (or does not) trigger compaction — gated so nothing is serialized when
         // debug logging is off.
@@ -251,12 +284,15 @@ export function createStepBudgetGuard(config) {
                 provider,
                 model,
                 messageCount: messages.length,
-                estimatedTokens: estimate,
-                thresholdTokens,
-                willCompact: estimate > thresholdTokens,
+                estimatedTokens: rawEstimate,
+                thresholdTokens: effectiveThreshold,
+                calibration,
+                observedInputTokensLastStep,
+                willCompact: rawEstimate > effectiveThreshold,
             });
         }
-        if (estimate <= thresholdTokens) {
+        if (rawEstimate <= effectiveThreshold) {
+            lastRawEstimate = rawEstimate;
             return undefined;
         }
         // Stage 1: shrink old tool outputs to previews.
@@ -265,25 +301,28 @@ export function createStepBudgetGuard(config) {
         let newEstimate = overheadTokens + estimateStepMessagesTokens(compacted, provider);
         // Stage 2: drop oldest complete tool exchanges if still over.
         let droppedExchanges = 0;
-        if (newEstimate > thresholdTokens) {
-            const stage2 = dropOldestToolExchanges(compacted, thresholdTokens, overheadTokens, provider);
+        if (newEstimate > effectiveThreshold) {
+            const stage2 = dropOldestToolExchanges(compacted, effectiveThreshold, overheadTokens, provider);
             compacted = stage2.messages;
             droppedExchanges = stage2.droppedExchanges;
             newEstimate =
                 overheadTokens + estimateStepMessagesTokens(compacted, provider);
         }
         if (stage1.truncated === 0 && droppedExchanges === 0) {
+            lastRawEstimate = rawEstimate;
             return undefined; // nothing actionable (already all-protected)
         }
         logger.info("[StepBudgetGuard] Compacted agent-loop step messages", {
             provider,
             model,
-            estimatedTokens: estimate,
-            thresholdTokens,
+            estimatedTokens: rawEstimate,
+            thresholdTokens: effectiveThreshold,
+            calibration,
             afterTokens: newEstimate,
             toolOutputsTruncated: stage1.truncated,
             exchangesDropped: droppedExchanges,
         });
+        lastRawEstimate = newEstimate;
         return compacted;
     };
 }

package/dist/lib/core/baseProvider.d.ts

@@ -185,6 +185,18 @@ export declare abstract class BaseProvider implements AIProvider {
      * IMPLEMENTATION NOTE: Uses streamText() under the hood and accumulates results
      * for consistency and better performance
      */
+    /**
+     * Ensure runtime-discovered model limits (context window, output-token
+     * ceiling) are registered before any budget math runs. Generation
+     * pipelines await this BEFORE `checkContextBudget`, and generate()/stream()
+     * await it before options normalization so `getSafeMaxTokens` sees the
+     * discovered output ceiling.
+     *
+     * Default no-op. Providers with a runtime discovery source override it
+     * (e.g. LiteLLM's `/model/info`). Implementations must NEVER reject —
+     * discovery failure degrades to the static defaults.
+     */
+    ensureModelLimits(): Promise<void>;
     generate(optionsOrPrompt: TextGenerationOptions | string, _analysisSchema?: ValidationSchema): Promise<EnhancedGenerateResult | null>;
     /**
      * Alias for generate method - implements AIProvider interface

package/dist/lib/core/baseProvider.js

@@ -118,6 +118,9 @@ export class BaseProvider {
      * When tools are involved, falls back to generate() with synthetic streaming
      */
     async stream(optionsOrPrompt, analysisSchema) {
+        // Runtime model limits must land before normalizeStreamOptions resolves
+        // maxTokens (getSafeMaxTokens consults the discovered output ceiling).
+        await this.ensureModelLimits();
         let options = this.normalizeStreamOptions(optionsOrPrompt);
         logger.info(`Starting stream`, {
             provider: this.providerName,
@@ -855,7 +858,22 @@ export class BaseProvider {
      * IMPLEMENTATION NOTE: Uses streamText() under the hood and accumulates results
      * for consistency and better performance
      */
+    /**
+     * Ensure runtime-discovered model limits (context window, output-token
+     * ceiling) are registered before any budget math runs. Generation
+     * pipelines await this BEFORE `checkContextBudget`, and generate()/stream()
+     * await it before options normalization so `getSafeMaxTokens` sees the
+     * discovered output ceiling.
+     *
+     * Default no-op. Providers with a runtime discovery source override it
+     * (e.g. LiteLLM's `/model/info`). Implementations must NEVER reject —
+     * discovery failure degrades to the static defaults.
+     */
+    async ensureModelLimits() { }
     async generate(optionsOrPrompt, _analysisSchema) {
+        // Runtime model limits must land before normalizeTextOptions resolves
+        // maxTokens (getSafeMaxTokens consults the discovered output ceiling).
+        await this.ensureModelLimits();
         const options = this.normalizeTextOptions(optionsOrPrompt);
         this.validateOptions(options);
         const startTime = Date.now();

package/dist/lib/core/modules/GenerationHandler.js

@@ -19,8 +19,9 @@ import { logger } from "../../utils/logger.js";
 import { emitToolEndFromStepFinish } from "../../utils/toolEndEmitter.js";
 import { calculateCost } from "../../utils/pricing.js";
 import { withProviderRetry } from "../../utils/providerRetry.js";
+import { parseTimeout } from "../../utils/timeout.js";
 import { calculateCacheSavingsPercent, extractCacheCreationTokens, extractCacheReadTokens, extractTokenUsage, } from "../../utils/tokenUtils.js";
-import { DEFAULT_MAX_STEPS } from "../constants.js";
+import { DEFAULT_MAX_STEPS, DEFAULT_WRAPUP_TIME_LEAD_MS, } from "../constants.js";
 import { createStepBudgetGuard, estimateFixedOverheadTokens, } from "../../context/stepBudgetGuard.js";
 import { isTemperatureDeprecatedError, isSchemaComplexityError, isToolsSchemaConflictError, isToolsSchemaExclusionInForce, } from "./structuredOutputPolicy.js";
 import { coerceJsonToSchema } from "../../utils/json/coerce.js";
@@ -45,6 +46,94 @@ function safePreview(v) {
         return "[unserializable]";
     }
 }
+/**
+ * Turn budget + wrap-up deadline (parity with the googleVertex native loops).
+ * A deadline is engaged only when the caller expressed one: turnTimeoutMs
+ * wins, else an explicit generate timeout. Callers that set neither keep the
+ * pre-existing behaviour (no wrap-up; the outer defensive timeout in
+ * executeStandardGenerateFlow still applies). With `wrapupTimeLeadMs` left of
+ * the deadline, the loop stops offering tools (toolChoice: "none") so the
+ * model spends the remaining budget producing a final answer instead of being
+ * guillotined mid-tool-loop with all work discarded. The lead is clamped to a
+ * quarter of the budget so short explicit timeouts (e.g. 30s) don't trigger
+ * wrap-up on the very first step.
+ *
+ * `turnStartMs` anchors the deadline to the ORIGINAL generation start:
+ * callGenerateText re-runs on executeGeneration's fallback retries
+ * (structured-output conflict, temperature-deprecated) and provider retries,
+ * and a deadline computed from Date.now() per attempt would hand each retry
+ * a fresh budget — multiplying the caller's wall-clock cap.
+ */
+function resolveTurnBudget(options, turnStartMs) {
+    const callerTimeoutMs = parseTimeout(options.timeout);
+    const hasValidTurnTimeout = typeof options.turnTimeoutMs === "number" &&
+        Number.isFinite(options.turnTimeoutMs) &&
+        options.turnTimeoutMs > 0;
+    if (options.turnTimeoutMs !== undefined && !hasValidTurnTimeout) {
+        logger.warn("[GenerationHandler] Ignoring invalid turnTimeoutMs — expected a positive number of milliseconds; falling back to the timeout option", { turnTimeoutMs: options.turnTimeoutMs });
+    }
+    const turnBudgetMs = hasValidTurnTimeout
+        ? options.turnTimeoutMs
+        : callerTimeoutMs;
+    const wrapupLeadMs = turnBudgetMs
+        ? Math.min(options.wrapupTimeLeadMs ?? DEFAULT_WRAPUP_TIME_LEAD_MS, Math.floor(turnBudgetMs / 4))
+        : 0;
+    const turnDeadline = turnBudgetMs ? turnStartMs + turnBudgetMs : undefined;
+    return { callerTimeoutMs, turnBudgetMs, wrapupLeadMs, turnDeadline };
+}
+/**
+ * Merge the per-call providerOptions namespaces for generateText. Both the
+ * timeout forwarding (`neurolink.timeoutMs`, read by NeuroLink's delegating
+ * chat-completions models) and Gemini thinking (`google.thinkingConfig`) may
+ * apply on the same call — built here as ONE object because two conditional
+ * `providerOptions:` spreads in the args literal would silently clobber each
+ * other (object spread does not deep-merge).
+ */
+function buildProviderOptions(options, isGoogleProvider, callerTimeoutMs) {
+    const providerOptions = {};
+    if (callerTimeoutMs !== undefined) {
+        providerOptions.neurolink = { timeoutMs: callerTimeoutMs };
+    }
+    if (options.thinkingConfig?.enabled && isGoogleProvider) {
+        // Gemini 3 uses thinkingLevel; Gemini 2.5 uses thinkingBudget.
+        providerOptions.google = {
+            thinkingConfig: {
+                ...(options.thinkingConfig.thinkingLevel && {
+                    thinkingLevel: options.thinkingConfig.thinkingLevel,
+                }),
+                ...(options.thinkingConfig.budgetTokens &&
+                    !options.thinkingConfig.thinkingLevel && {
+                    thinkingBudget: options.thinkingConfig.budgetTokens,
+                }),
+                includeThoughts: true,
+            },
+        };
+    }
+    return Object.keys(providerOptions).length > 0
+        ? providerOptions
+        : undefined;
+}
+/**
+ * Build the prepareStep result for a forced wrap-up step: tools withdrawn
+ * (toolChoice: "none") plus an honest time message (native-loop parity) —
+ * without the message, weaker models keep trying to emit tool calls and leak
+ * raw tool-call tokens into the text answer.
+ */
+function buildWrapupStepResult(prepared, stepMessages) {
+    const baseMessages = prepared?.messages ??
+        stepMessages;
+    return {
+        ...(prepared ?? {}),
+        messages: [
+            ...baseMessages,
+            {
+                role: "user",
+                content: "The time budget for this task is nearly exhausted. Do not call any more tools. Give your best final answer NOW from the information already gathered, and note anything you could not verify in the remaining time.",
+            },
+        ],
+        toolChoice: "none",
+    };
+}
 /**
  * GenerationHandler class - Handles text generation operations for AI providers
  */
@@ -67,7 +156,8 @@ export class GenerationHandler {
      * Helper method to call generateText with optional structured output
      * @private
      */
-    async callGenerateText(model, messages, tools, options, shouldUseTools, includeStructuredOutput) {
+    async callGenerateText(model, messages, tools, options, callConfig) {
+        const { shouldUseTools, includeStructuredOutput, turnStartMs } = callConfig;
         // Check if this is a Google provider (for provider-specific options)
         const isGoogleProvider = this.providerName === "google-ai" || this.providerName === "vertex";
         // Check if this is an Anthropic provider (includes Vertex+Claude)
@@ -113,6 +203,9 @@ export class GenerationHandler {
             }
         }
         const prepareStep = options.prepareStep;
+        const { callerTimeoutMs, turnBudgetMs, wrapupLeadMs, turnDeadline } = resolveTurnBudget(options, turnStartMs);
+        let wrapupForced = false;
+        const providerOptions = buildProviderOptions(options, isGoogleProvider, callerTimeoutMs);
         // Hoist system-role messages into generateText's top-level `system` option
         // rather than passing them inside `messages` (deprecated by the AI SDK,
         // rejected in v7). See extractSystemMessages for the rationale. (#1024)
@@ -148,7 +241,7 @@ export class GenerationHandler {
                 return cachedOverhead.tokens;
             },
         });
-        return await generateText({
+        const result = await generateText({
             model,
             ...(system && { system }),
             messages: nonSystemMessages,
@@ -173,52 +266,72 @@ export class GenerationHandler {
                 // the step's own messages. It never replaces a caller's content
                 // choices — it only reclaims budget from whatever was chosen.
                 const callerMessages = callerResult?.messages;
-                const compacted = stepBudgetGuard(callerMessages ?? stepOptions.messages);
-                if (!compacted) {
-                    return callerResult;
+                // Usage feedback: the provider's REAL prompt-token count for the
+                // previous step calibrates the guard's char-based estimator (see
+                // createStepBudgetGuard) — free precision, no tokenizer.
+                const previousStep = stepOptions.steps[stepOptions.steps.length - 1];
+                const compacted = stepBudgetGuard(callerMessages ?? stepOptions.messages, previousStep?.usage?.inputTokens);
+                const prepared = compacted
+                    ? { ...(callerResult ?? {}), messages: compacted }
+                    : callerResult;
+                // Wrap-up: inside the lead window before the turn deadline, stop
+                // offering tools so this step produces the final answer. Overrides
+                // any caller toolChoice — an honest partial beats a discarded turn.
+                if (turnDeadline !== undefined &&
+                    shouldUseTools &&
+                    Date.now() >= turnDeadline - wrapupLeadMs) {
+                    if (!wrapupForced) {
+                        wrapupForced = true;
+                        logger.warn("[GenerationHandler] Turn budget nearly exhausted — forcing wrap-up (toolChoice: none)", {
+                            provider: this.providerName,
+                            turnBudgetMs,
+                            wrapupLeadMs,
+                            stepNumber: stepOptions.stepNumber,
+                        });
+                    }
+                    return buildWrapupStepResult(prepared, stepOptions.messages);
                 }
-                return { ...(callerResult ?? {}), messages: compacted };
+                return prepared;
             }),
             temperature: options.temperature,
             maxOutputTokens: options.maxTokens,
             maxRetries: 0, // NL11: Disable AI SDK's invisible internal retries; we handle retries with OTel instrumentation
             abortSignal: options.abortSignal,
+            // Schema-driven tool-call repair (BZ-665): fixes near-miss tool names
+            // (case/substring/Levenshtein) and — for tools whose schema carries a
+            // validator — coerces mis-typed arguments ("123" → 123) and remaps
+            // near-miss parameter names before the call is marked invalid. Wired
+            // for every AI-SDK-loop provider; native loops have their own paths.
+            ...(shouldUseTools &&
+                !options.disableToolCallRepair && {
+                experimental_repairToolCall: (async (...repairArgs) => {
+                    // Lazy import to avoid a circular dependency at module load time
+                    const { createToolCallRepair } = await import("../../utils/toolCallRepair.js");
+                    return createToolCallRepair()(...repairArgs);
+                }),
+            }),
+            // Forward the caller's resolved timeout to the model layer: the AI-SDK
+            // V3 call options carry no `timeout`, so delegating chat-completions
+            // models (litellm & friends) could otherwise only ever apply their
+            // provider default per step — an explicit `timeout: "15m"` bounded the
+            // outer loop while each step stayed capped at the default.
+            // Merged namespaces (neurolink timeout forwarding + Gemini thinking) —
+            // built as ONE object; see buildProviderOptions.
+            ...(providerOptions && { providerOptions }),
             ...(useStructuredOutput &&
                 options.schema && {
                 experimental_output: Output.object({ schema: options.schema }),
             }),
-            // Add thinking configuration for extended reasoning
-            // Gemini 3 models use providerOptions.google.thinkingConfig with thinkingLevel
-            // Gemini 2.5 models use thinkingBudget
-            // Anthropic models use experimental_thinking with budgetTokens
-            ...(options.thinkingConfig?.enabled && {
-                // For Anthropic: experimental_thinking with budgetTokens
-                ...(isAnthropicProvider &&
-                    options.thinkingConfig.budgetTokens &&
-                    !options.thinkingConfig.thinkingLevel && {
-                    experimental_thinking: {
-                        type: "enabled",
-                        budgetTokens: options.thinkingConfig.budgetTokens,
-                    },
-                }),
-                // For Google Gemini 3: providerOptions with thinkingLevel
-                // For Gemini 2.5: providerOptions with thinkingBudget
-                ...(isGoogleProvider && {
-                    providerOptions: {
-                        google: {
-                            thinkingConfig: {
-                                ...(options.thinkingConfig.thinkingLevel && {
-                                    thinkingLevel: options.thinkingConfig.thinkingLevel,
-                                }),
-                                ...(options.thinkingConfig.budgetTokens &&
-                                    !options.thinkingConfig.thinkingLevel && {
-                                    thinkingBudget: options.thinkingConfig.budgetTokens,
-                                }),
-                                includeThoughts: true,
-                            },
-                        },
-                    },
-                }),
+            // Anthropic thinking: experimental_thinking with budgetTokens.
+            // (Gemini thinking rides providerOptions.google above.)
+            ...(options.thinkingConfig?.enabled &&
+                isAnthropicProvider &&
+                options.thinkingConfig.budgetTokens &&
+                !options.thinkingConfig.thinkingLevel && {
+                experimental_thinking: {
+                    type: "enabled",
+                    budgetTokens: options.thinkingConfig.budgetTokens,
+                },
             }),
             experimental_telemetry: this.getTelemetryConfigFn(options, "generate"),
             onStepFinish: ({ toolCalls, toolResults }) => {
@@ -237,6 +350,16 @@ export class GenerationHandler {
                 });
             },
         });
+        if (wrapupForced) {
+            // Non-enumerable marker read by formatEnhancedResult to report
+            // stopReason "time-limit" — the result object itself is the only
+            // artifact that travels from this call to result formatting.
+            Object.defineProperty(result, "__nlTurnWrapup", {
+                value: true,
+                enumerable: false,
+            });
+        }
+        return result;
     }
     /**
      * Execute the generation with AI SDK
@@ -293,7 +416,11 @@ export class GenerationHandler {
             }
             const genStartTime = Date.now();
             try {
-                const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, shouldUseTools, true), span, "generateText");
+                const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, {
+                    shouldUseTools,
+                    includeStructuredOutput: true,
+                    turnStartMs: genStartTime,
+                }), span, "generateText");
                 logger.info("[GenerationHandler] generateText returned", {
                     requestId,
                     durationMs: Date.now() - genStartTime,
@@ -388,7 +515,12 @@ export class GenerationHandler {
                     }
                     // Retry without experimental_output - the formatEnhancedResult method
                     // will extract JSON from the text response
-                    const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, shouldUseTools, false), span, "generateText(fallback)");
+                    const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, {
+                        shouldUseTools,
+                        // includeStructuredOutput intentionally omitted
+                        includeStructuredOutput: false,
+                        turnStartMs: genStartTime,
+                    }), span, "generateText(fallback)");
                     // NLK-GAP-007: Record recovery event after successful fallback
                     span.addEvent("retry.recovered", {
                         "retry.attempts": 2,
@@ -439,7 +571,12 @@ export class GenerationHandler {
                         model: this.modelName,
                         error: error instanceof Error ? error.message : String(error),
                     });
-                    const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, { ...options, temperature: undefined }, shouldUseTools, true), span, "generateText(no-temperature)");
+                    const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, { ...options, temperature: undefined }, {
+                        shouldUseTools,
+                        // mirror the initial call; the structured-output policy still applies
+                        includeStructuredOutput: true,
+                        turnStartMs: genStartTime,
+                    }), span, "generateText(no-temperature)");
                     span.addEvent("retry.recovered", {
                         "retry.attempts": 2,
                         "retry.strategy": "temperature_omitted",
@@ -722,11 +859,40 @@ export class GenerationHandler {
                     : String(rawReasoning)
             : undefined;
         const reasoningTokens = usage.reasoning ?? undefined;
+        // stopReason / stepsUsed parity with the native loops (Vertex Gemini /
+        // Claude / Bedrock): the AI-SDK loop path previously left both undefined,
+        // so consumers could not distinguish a completed turn from one truncated
+        // by the step cap or ended by the turn budget.
+        const steps = generateResult.steps;
+        const stepsUsed = Array.isArray(steps) ? steps.length : undefined;
+        const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+        let stopReason;
+        if (generateResult.__nlTurnWrapup === true) {
+            stopReason = "time-limit";
+        }
+        else if (stepsUsed !== undefined &&
+            stepsUsed >= maxSteps &&
+            generateResult.finishReason === "tool-calls") {
+            stopReason = "step-cap";
+        }
+        else if (generateResult.finishReason === "error") {
+            // Parity with resolveTurnStopReason (native loops): a turn that ended
+            // on a provider "error" finish is not a completion. length /
+            // content-filter DO map to "completed" — deliberately matching the
+            // native contract, where truncation is signaled via finishReason /
+            // rawFinishReason / jsonTruncated, never via stopReason.
+            stopReason = "provider-error";
+        }
+        else if (stepsUsed !== undefined) {
+            stopReason = "completed";
+        }
         return {
             content,
             structuredData,
             usage,
             finishReason: generateResult.finishReason,
+            stopReason,
+            stepsUsed,
             jsonRepaired: jsonRepaired || undefined,
             jsonTruncated: jsonTruncated || undefined,
             provider: this.providerName,

package/dist/lib/core/modules/ToolsManager.d.ts

@@ -1,6 +1,23 @@
 import type { AIProviderName, ToolUtilities } from "../../types/index.js";
 import type { NeuroLink } from "../../neurolink.js";
 import type { Tool } from "../../types/index.js";
+/**
+ * Build an argument validator for an external MCP tool's JSON Schema, in the
+ * shape the AI SDK's `jsonSchema()` wrapper expects. Returns undefined when
+ * the schema can't be compiled (exotic dialect) — the tool then keeps the
+ * previous declarative-only behaviour instead of failing registration.
+ *
+ * The error message is written for the MODEL (it is fed back verbatim as the
+ * tool-error text): it names the offending fields and restates the contract
+ * (required properties + types) so the retry can succeed on the first attempt.
+ */
+export declare function buildMCPSchemaValidator(toolName: string, schema: Record<string, unknown>): Promise<((value: unknown) => {
+    success: true;
+    value: unknown;
+} | {
+    success: false;
+    error: Error;
+}) | undefined>;
 /**
  * ToolsManager class - Handles all tool management operations
  */

package/dist/lib/core/modules/ToolsManager.js

@@ -13,6 +13,87 @@ function makeToolAbortError() {
     e.name = "AbortError";
     return e;
 }
+/**
+ * Compiled-validator cache, keyed by the ORIGINAL MCP tool inputSchema
+ * object. createExternalMCPTool runs once per external tool on EVERY
+ * getAllTools() (i.e. every generation call), and the schema object identity
+ * is stable for the lifetime of a server connection — without the cache the
+ * same JSON Schema is recompiled on every generate() (hot-path CPU for
+ * 50+-tool deployments). Rediscovery produces new schema objects, so stale
+ * entries fall out via WeakMap semantics. `undefined` values (schemas that
+ * failed to compile) are cached too — hence has()/get() rather than a
+ * get()-only check.
+ */
+const mcpValidatorCache = new WeakMap();
+/**
+ * Build an argument validator for an external MCP tool's JSON Schema, in the
+ * shape the AI SDK's `jsonSchema()` wrapper expects. Returns undefined when
+ * the schema can't be compiled (exotic dialect) — the tool then keeps the
+ * previous declarative-only behaviour instead of failing registration.
+ *
+ * The error message is written for the MODEL (it is fed back verbatim as the
+ * tool-error text): it names the offending fields and restates the contract
+ * (required properties + types) so the retry can succeed on the first attempt.
+ */
+export async function buildMCPSchemaValidator(toolName, schema) {
+    try {
+        const { Validator } = await import("@cfworker/json-schema");
+        // draft-07: the lingua franca of MCP server inputSchemas. shortCircuit
+        // false so the error lists every violation, not just the first.
+        const validator = new Validator(schema, "7", false);
+        const required = Array.isArray(schema.required)
+            ? schema.required
+            : [];
+        const properties = schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+        const contract = Object.entries(properties)
+            .map(([key, prop]) => `${key}${required.includes(key) ? "" : "?"}: ${prop?.type ?? "any"}`)
+            .join(", ");
+        return (value) => {
+            try {
+                const result = validator.validate(value);
+                if (result.valid) {
+                    return { success: true, value };
+                }
+                // Root-level entries ("#") are mostly generic "instance does not
+                // match schema" noise — EXCEPT missing-required errors, which carry
+                // the offending property name and must reach the model.
+                const details = result.errors
+                    .filter((e) => e.instanceLocation !== "#" || /required property/i.test(e.error))
+                    .slice(0, 3)
+                    .map((e) => {
+                    const loc = e.instanceLocation.replace(/^#\/?/, "");
+                    return loc ? `${loc}: ${e.error}` : e.error;
+                })
+                    .join("; ");
+                return {
+                    success: false,
+                    error: new Error(`Invalid arguments for tool '${toolName}'${details ? ` — ${details}` : ""}. ` +
+                        `Expected: { ${contract} } (send every non-optional property with the exact name and JSON type).`),
+                };
+            }
+            catch (validationError) {
+                // Validator crashed on this instance — treat as valid rather than
+                // block the call; the MCP-layer validator still backstops execution.
+                logger.debug(`[ToolsManager] Schema validator failed for '${toolName}', passing through`, {
+                    error: validationError instanceof Error
+                        ? validationError.message
+                        : String(validationError),
+                });
+                return { success: true, value };
+            }
+        };
+    }
+    catch (compileError) {
+        logger.debug(`[ToolsManager] Could not compile schema validator for '${toolName}' — arguments will not be pre-validated`, {
+            error: compileError instanceof Error
+                ? compileError.message
+                : String(compileError),
+        });
+        return undefined;
+    }
+}
 /**
  * Race a tool-execution promise against an AbortSignal so the calling loop
  * observes a deadline/caller abort IMMEDIATELY instead of waiting for the
@@ -583,7 +664,24 @@ export class ToolsManager {
                 const fixedSchema = this.utilities?.fixSchemaForOpenAIStrictMode
                     ? this.utilities.fixSchemaForOpenAIStrictMode(originalSchema)
                     : originalSchema;
-                finalSchema = jsonSchema(fixedSchema);
+                // A jsonSchema() wrapper WITHOUT a validate function is declarative
+                // only — the AI SDK passes any parsed arguments straight through
+                // (safeValidateTypes short-circuits on `validate == null`). That let
+                // malformed calls (missing required params, "123" for a number)
+                // reach execution, where the MCP-layer validator rejected them at
+                // the cost of a full model round-trip. Attach a real validator so
+                // invalid calls fail at parse time, where experimental_repairToolCall
+                // can still fix them silently. Compiled once per schema object —
+                // see mcpValidatorCache.
+                let validate;
+                if (mcpValidatorCache.has(originalSchema)) {
+                    validate = mcpValidatorCache.get(originalSchema);
+                }
+                else {
+                    validate = await buildMCPSchemaValidator(tool.name, fixedSchema);
+                    mcpValidatorCache.set(originalSchema, validate);
+                }
+                finalSchema = jsonSchema(fixedSchema, validate ? { validate } : {});
             }
             else {
                 finalSchema = this.utilities?.createPermissiveZodSchema