@juspay/neurolink 10.3.0 → 10.4.0

package/dist/lib/types/stream.d.ts

@@ -1,6 +1,7 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "./evaluation.js";
 import type { RAGConfig } from "./rag.js";
+import type { KnowledgeGroundingMetadata, KnowledgeRequestScope } from "./knowledge.js";
 import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
 import type { MiddlewareFactoryOptions, OnChunkCallback, OnErrorCallback, OnFinishCallback } from "../types/middleware.js";
@@ -169,6 +170,17 @@ export type StreamChunk = {
     audio: TTSChunk;
 };
 export type StreamOptions = {
+    /**
+     * Opt this stream call into the knowledge grounding configured on the
+     * NeuroLink instance. Defaults to `false` when omitted.
+     */
+    useKnowledgeGrounding?: boolean;
+    /**
+     * Enabled integrations used to scope knowledge retrieval for this turn.
+     * Used only when `useKnowledgeGrounding` is true and knowledge grounding is
+     * enabled on the NeuroLink instance.
+     */
+    knowledgeContext?: KnowledgeRequestScope;
     input: {
         /** Prompt text. Optional for media-only modes (avatar, music) that are driven by uploaded files rather than a prompt. */
         text?: string;
@@ -552,6 +564,8 @@ export type StreamOptions = {
  * Future-ready for multi-modal outputs while maintaining text focus
  */
 export type StreamResult = {
+    /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
+    knowledge?: KnowledgeGroundingMetadata;
     stream: AsyncIterable<{
         content: string;
         reasoning?: string;

package/dist/lib/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/lib/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/lib/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/lib/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/lib/utils/timeout.js

@@ -342,26 +342,86 @@ 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;
 }
 //# sourceMappingURL=timeout.js.map

package/dist/lib/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/lib/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/lib/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;

package/dist/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}`);

package/dist/neurolink.d.ts

@@ -6,7 +6,7 @@
  * Uses real MCP infrastructure for tool discovery and execution.
  */
 import type { AgentDefinition, AgentNetworkConfig, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk } from "./types/index.js";
-import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig } from "./types/index.js";
+import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -107,6 +107,7 @@ export declare class NeuroLink {
     private toolRoutingConfig?;
     private toolRoutingCacheInstance?;
     private toolRoutingVectorCache?;
+    private knowledgeGroundingEngine?;
     private toolDedupConfig?;
     private toolsConfig?;
     /** Session-scoped pins of tools discovered via search_tools (tools.discovery mode). */
@@ -629,6 +630,7 @@ export declare class NeuroLink {
      * @param optionsOrPrompt.maxTokens - Maximum tokens to generate
      * @param optionsOrPrompt.thinkingConfig - Extended thinking configuration (thinkingLevel: 'minimal'|'low'|'medium'|'high')
      * @param optionsOrPrompt.context - Context with conversationId and userId for memory
+     * @param optionsOrPrompt.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      * @returns Promise resolving to generation result with content and metadata
      *
      * @example Basic text generation
@@ -904,6 +906,7 @@ export declare class NeuroLink {
      * @param options.enableEvaluation - Whether to include response quality evaluation
      * @param options.context - Additional context for the request
      * @param options.evaluationDomain - Domain for specialized evaluation
+     * @param options.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      *
      * @returns Promise resolving to StreamResult with an async iterable stream
      *
@@ -989,6 +992,16 @@ export declare class NeuroLink {
      * alone does not activate it.
      */
     setToolRoutingServers(servers: ToolRoutingServerDescriptor[]): void;
+    /** Knowledge-grounding engine health (null when it was not configured). */
+    getKnowledgeStatus(): KnowledgeEngineStatus | null;
+    private appendKnowledgeGroundingBlockToSystemPrompt;
+    /**
+     * Retrieve knowledge grounding for a public generate/stream call without
+     * mutating its options. The outer call boundary decides how to apply the
+     * returned context. Returns undefined when the call does not opt in,
+     * grounding is disabled/not applicable, or retrieval fails open.
+     */
+    private retrieveKnowledgeGrounding;
     private validateStreamRequestOptions;
     private maybeHandleWorkflowStreamRequest;
     private runStandardStreamRequest;