@juspay/neurolink 10.2.2 → 10.3.1

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

@@ -19,8 +19,10 @@ 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";
 import { NoObjectGeneratedError } from "../../utils/generationErrors.js";
@@ -44,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
  */
@@ -66,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)
@@ -112,11 +203,45 @@ 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)
         const { system, messages: nonSystemMessages } = extractSystemMessages(messages);
-        return await generateText({
+        // Per-step context budget guard: the tool loop appends assistant turns and
+        // tool results on every step — growth the pre-call budget check never
+        // sees. Estimate each step's projected request and deterministically
+        // reclaim budget (truncate old tool outputs, then drop oldest exchanges)
+        // so long agentic runs cannot overflow the model's window mid-loop.
+        // Parity with the googleVertex native loops' createContextGuard, upgraded
+        // from stop-only to compact-and-continue. The caller's prepareStep result
+        // wins on conflicts; the guard only contributes `messages`.
+        //
+        // Overhead is resolved PER STEP because `toolsWithCache` is deliberately
+        // mutable (search_tools hydration adds discovered tools mid-loop) — a
+        // once-captured estimate would undercount later steps. Tools are only
+        // ever added, so memoizing on tool count keeps the common step O(1).
+        let cachedOverhead = { toolCount: -1, tokens: 0 };
+        const stepBudgetGuard = createStepBudgetGuard({
+            provider: this.providerName ?? "unknown",
+            model: this.modelName,
+            maxTokens: options.maxTokens,
+            getFixedOverheadTokens: () => {
+                const toolCount = shouldUseTools
+                    ? Object.keys(toolsWithCache).length
+                    : 0;
+                if (toolCount !== cachedOverhead.toolCount) {
+                    cachedOverhead = {
+                        toolCount,
+                        tokens: estimateFixedOverheadTokens(system, shouldUseTools ? toolsWithCache : undefined, this.providerName),
+                    };
+                }
+                return cachedOverhead.tokens;
+            },
+        });
+        const result = await generateText({
             model,
             ...(system && { system }),
             messages: nonSystemMessages,
@@ -125,52 +250,88 @@ export class GenerationHandler {
             stopWhen: stepCountIs(options.maxSteps ?? DEFAULT_MAX_STEPS),
             ...(shouldUseTools &&
                 options.toolChoice && { toolChoice: options.toolChoice }),
-            ...(prepareStep && {
-                experimental_prepareStep: ((stepOptions) => prepareStep({
-                    ...stepOptions,
-                    maxSteps: options.maxSteps ?? DEFAULT_MAX_STEPS,
-                })),
+            experimental_prepareStep: (async (stepOptions) => {
+                // Public contract preserved: a caller-supplied prepareStep receives
+                // the ORIGINAL AI-SDK step options, exactly as before the guard
+                // existed — callers that inspect message history see the real thing.
+                const callerResult = prepareStep
+                    ? await prepareStep({
+                        ...stepOptions,
+                        maxSteps: options.maxSteps ?? DEFAULT_MAX_STEPS,
+                    })
+                    : undefined;
+                // The guard runs LAST, on the messages that will actually be sent:
+                // the caller's override when one was returned (out-of-contract for
+                // NeuroLink's public prepareStep type, but possible at runtime), else
+                // 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;
+                // 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 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 }) => {
@@ -189,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
@@ -245,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,
@@ -340,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,
@@ -391,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",
@@ -674,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

package/dist/lib/mcp/toolDiscoveryService.js

@@ -9,6 +9,7 @@ import { globalCircuitBreakerManager, CircuitBreakerOpenError, } from "./mcpCirc
 import { isObject, isNullish } from "../utils/typeUtils.js";
 import { validateToolName, validateToolDescription, } from "../utils/parameterValidation.js";
 import { withTimeout } from "../utils/errorHandling.js";
+import { coerceType } from "../utils/toolCallRepair.js";
 import { extractMcpErrorText } from "../utils/mcpErrorText.js";
 import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
 import { tracers } from "../telemetry/tracers.js";
@@ -416,12 +417,16 @@ export class ToolDiscoveryService extends EventEmitter {
             if (!toolInfo.isAvailable) {
                 throw new Error(`Tool '${toolName}' is not available`);
             }
-            // Validate input parameters if requested
+            // Validate input parameters if requested. Validation coerces
+            // recoverable mismatches (numeric strings for number params, "true"
+            // for booleans, JSON-encoded objects/arrays) instead of rejecting —
+            // a rejection here costs the agent loop a full model round-trip.
+            let effectiveParameters = parameters;
             if (options.validateInput !== false) {
-                this.validateToolParameters(toolInfo, parameters);
+                effectiveParameters = this.validateToolParameters(toolInfo, parameters);
             }
             mcpLogger.debug(`[ToolDiscoveryService] Executing tool: ${toolName} on ${serverId}`, {
-                parameters,
+                parameters: effectiveParameters,
             });
             // Create circuit breaker for tool execution
             const effectiveTimeout = options.timeout || DEFAULT_TOOL_TIMEOUT;
@@ -448,16 +453,22 @@ export class ToolDiscoveryService extends EventEmitter {
                         "gen_ai.tool.name": toolName,
                         "gen_ai.request": safeJsonStringify({
                             name: toolName,
-                            arguments: redactForPreview(parameters),
+                            arguments: redactForPreview(effectiveParameters),
                         }, 2048),
                     },
                 }, async (callSpan) => {
                     try {
                         const timeout = effectiveTimeout;
+                        // Pass the timeout as MCP RequestOptions too: without it the
+                        // SDK applies its own DEFAULT_REQUEST_TIMEOUT_MSEC (60s), so a
+                        // configured server timeout above 60s never took effect — the
+                        // SDK aborted first. The SDK timeout also cancels the transport
+                        // request and sends a cancellation notification, which the
+                        // outer Promise.race below (kept as a backstop) cannot do.
                         const callResult = await withTimeout(client.callTool({
                             name: toolName,
-                            arguments: parameters,
-                        }), timeout, new Error(`Tool execution timeout: ${toolName}`));
+                            arguments: effectiveParameters,
+                        }, undefined, { timeout: effectiveTimeout }), timeout, new Error(`Tool execution timeout: ${toolName}`));
                         // Curator P0-1/P0-2: the MCP client does NOT throw on protocol
                         // errors — it returns { isError: true, content: [...] }. Detect
                         // that pattern so the span status reflects reality.
@@ -603,25 +614,45 @@ export class ToolDiscoveryService extends EventEmitter {
      */
     validateToolParameters(toolInfo, parameters) {
         if (!toolInfo.inputSchema) {
-            return; // No schema to validate against
+            return parameters; // No schema to validate against
         }
-        // Basic validation - check required properties
         const schema = toolInfo.inputSchema;
-        if (schema.required && Array.isArray(schema.required)) {
-            for (const requiredProp of schema.required) {
-                if (typeof requiredProp === "string" && !(requiredProp in parameters)) {
-                    throw new Error(`Missing required parameter: ${requiredProp}`);
-                }
-            }
-        }
-        // Type validation for properties
-        if (schema.properties) {
-            for (const [propName, propSchema] of Object.entries(schema.properties)) {
-                if (propName in parameters) {
-                    this.validateParameterType(propName, parameters[propName], propSchema);
+        const properties = schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+        const requiredProps = Array.isArray(schema.required)
+            ? schema.required.filter((r) => typeof r === "string")
+            : [];
+        // The thrown message is fed back to the MODEL as the tool result, so it
+        // restates the full contract — a bare "missing X" made weaker models
+        // guess again and burn another loop step per attempt.
+        const contract = () => Object.entries(properties)
+            .map(([key, prop]) => `${key}${requiredProps.includes(key) ? "" : "?"}: ${prop.type ?? "any"}`)
+            .join(", ");
+        // Basic validation - check required properties
+        const missing = requiredProps.filter((prop) => !(prop in parameters));
+        if (missing.length > 0) {
+            throw new Error(`Missing required parameter${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}. ` +
+                `Expected arguments: { ${contract()} }; received keys: [${Object.keys(parameters).join(", ")}]`);
+        }
+        // Type validation for properties — coerce recoverable mismatches first
+        // (numeric strings, "true"/"false", JSON-encoded objects/arrays) so a
+        // sloppy-but-unambiguous call executes instead of failing back to the
+        // model. Only genuinely wrong types still throw.
+        let coerced;
+        for (const [propName, propSchema] of Object.entries(properties)) {
+            if (propName in parameters) {
+                const originalValue = parameters[propName];
+                const coercedValue = coerceType(originalValue, propSchema);
+                if (coercedValue !== originalValue) {
+                    mcpLogger.debug(`[ToolDiscoveryService] Coerced parameter '${propName}' for tool '${toolInfo.name}': ${typeof originalValue} → ${typeof coercedValue}`);
+                    coerced = coerced ?? { ...parameters };
+                    coerced[propName] = coercedValue;
                 }
+                this.validateParameterType(propName, (coerced ? coerced[propName] : originalValue), propSchema);
             }
         }
+        return coerced ?? parameters;
     }
     /**
      * Validate parameter type
@@ -643,6 +674,14 @@ export class ToolDiscoveryService extends EventEmitter {
                     throw new Error(`Parameter '${name}' must be a number, got ${actualType}`);
                 }
                 break;
+            case "integer":
+                // coerceType treats "integer" as distinct from "number"; without
+                // this case an uncoercible value ("3.7", "abc") passed through to
+                // the MCP server unvalidated.
+                if (actualType !== "number" || !Number.isInteger(value)) {
+                    throw new Error(`Parameter '${name}' must be an integer, got ${actualType === "number" ? String(value) : actualType}`);
+                }
+                break;
             case "boolean":
                 if (actualType !== "boolean") {
                     throw new Error(`Parameter '${name}' must be a boolean, got ${actualType}`);