@juspay/neurolink 10.3.0 → 10.4.0

package/dist/lib/knowledge/retrieval.js

@@ -0,0 +1,222 @@
+/**
+ * Lexical-first retrieval pipeline.
+ *
+ * For one turn: authorize/filter BEFORE ranking, resolve exact identifiers and
+ * reviewed aliases via query n-gram lookup, add field-aware BM25 over a bounded
+ * query+history window, combine the deterministic signals, take the top
+ * candidates, expand a bounded set of directly-related entries, and classify
+ * confidence. No LLM, no embeddings, no vector store.
+ */
+import { tokenize } from "./normalize.js";
+/** Per-turn history text cap so a long prior turn cannot dominate the query. */
+const HISTORY_TURN_CHARS = 400;
+/** All contiguous token n-grams (length 1..maxLen), de-duplicated. */
+const generateNGrams = (tokens, maxLen) => {
+    const grams = [];
+    const seen = new Set();
+    const limit = Math.min(maxLen, tokens.length);
+    for (let size = 1; size <= limit; size += 1) {
+        for (let start = 0; start + size <= tokens.length; start += 1) {
+            const gram = tokens.slice(start, start + size).join(" ");
+            if (!seen.has(gram)) {
+                seen.add(gram);
+                grams.push(gram);
+            }
+        }
+    }
+    return grams;
+};
+/** Longest indexed exact/alias phrase length, derived from the active snapshot. */
+const getMaxIndexedPhraseLen = (...indexes) => {
+    let maxLen = 0;
+    for (const index of indexes) {
+        for (const phrase of index.keys()) {
+            const length = phrase === "" ? 0 : phrase.split(" ").length;
+            maxLen = Math.max(maxLen, length);
+        }
+    }
+    return maxLen;
+};
+/** Look each n-gram up in a phrase index; returns entry id -> matched phrases. */
+const lookupPhrases = (grams, index) => {
+    const hits = new Map();
+    for (const gram of grams) {
+        const ids = index.get(gram);
+        if (!ids) {
+            continue;
+        }
+        for (const id of ids) {
+            const matched = hits.get(id) ?? [];
+            matched.push(gram);
+            hits.set(id, matched);
+        }
+    }
+    return hits;
+};
+/** Tokens fed to BM25: the current query plus a bounded recent-turn window. */
+const buildLexicalTokens = (request) => {
+    const parts = [request.query];
+    for (const turn of request.recentTurns) {
+        parts.push(turn.text.slice(0, HISTORY_TURN_CHARS));
+    }
+    return parts.flatMap((part) => tokenize(part));
+};
+/**
+ * Authorization + metadata filter. Applied BEFORE ranking so restricted or
+ * disabled-integration content never enters candidates, traces, or model context.
+ */
+const isAuthorized = (entry, request, blockedDomains) => {
+    if (entry.status !== "active") {
+        return false;
+    }
+    if (blockedDomains && blockedDomains.includes(entry.domain)) {
+        return false;
+    }
+    if (entry.integrations.length > 0) {
+        const active = new Set();
+        for (const integration of request.enabledIntegrations) {
+            active.add(integration.toLowerCase());
+        }
+        if (!entry.integrations.some((integration) => active.has(integration.toLowerCase()))) {
+            return false;
+        }
+    }
+    return true;
+};
+const compareCandidates = (left, right) => {
+    if (right.score !== left.score) {
+        return right.score - left.score;
+    }
+    if (left.id < right.id) {
+        return -1;
+    }
+    if (left.id > right.id) {
+        return 1;
+    }
+    return 0;
+};
+/**
+ * Confidence class. `high` requires an exact/alias hit at the top; otherwise a
+ * multi-field or dominant lexical top is `medium`, a single weak signal is
+ * `low`, and no candidates is `none`. Thresholds are pre-tuning heuristics.
+ */
+const classifyConfidence = (candidates) => {
+    if (candidates.length === 0) {
+        return "none";
+    }
+    const [top, second] = candidates;
+    if (top.exact || top.alias) {
+        return "high";
+    }
+    const fieldsMatched = Object.keys(top.fieldScores).length;
+    const dominant = second ? top.score >= 1.5 * second.score : false;
+    if (fieldsMatched >= 2 || dominant) {
+        return "medium";
+    }
+    return "low";
+};
+/**
+ * Run retrieval against a ready snapshot. Returns the primary selection, a
+ * bounded relationship expansion, the scored candidate list (diagnostics), and
+ * a confidence class. Context assembly is a separate, later step.
+ */
+export const retrieve = (snapshot, request, config, blockedDomains) => {
+    const queryTokens = tokenize(request.query);
+    const maxPhraseLen = getMaxIndexedPhraseLen(snapshot.exactIndex, snapshot.aliasIndex);
+    const grams = generateNGrams(queryTokens, maxPhraseLen);
+    const exactHits = lookupPhrases(grams, snapshot.exactIndex);
+    const aliasHits = lookupPhrases(grams, snapshot.aliasIndex);
+    const eligibleEntryIds = new Set();
+    for (const [id, entry] of snapshot.entriesById) {
+        if (isAuthorized(entry, request, blockedDomains)) {
+            eligibleEntryIds.add(id);
+        }
+    }
+    const lexicalTokens = buildLexicalTokens(request);
+    const lexicalMatches = snapshot.lexical.search(lexicalTokens, config.candidateLimit * 2, eligibleEntryIds);
+    const lexicalById = new Map(lexicalMatches.map((match) => [match.id, match]));
+    const candidateIds = new Set();
+    for (const id of exactHits.keys()) {
+        if (eligibleEntryIds.has(id)) {
+            candidateIds.add(id);
+        }
+    }
+    for (const id of aliasHits.keys()) {
+        if (eligibleEntryIds.has(id)) {
+            candidateIds.add(id);
+        }
+    }
+    for (const match of lexicalMatches) {
+        candidateIds.add(match.id);
+    }
+    const candidates = [];
+    for (const id of candidateIds) {
+        const entry = snapshot.entriesById.get(id);
+        if (!entry) {
+            continue;
+        }
+        const exact = exactHits.has(id);
+        const alias = aliasHits.has(id);
+        const lexicalMatch = lexicalById.get(id);
+        const lexical = lexicalMatch?.score ?? 0;
+        let score = lexical;
+        if (exact) {
+            score += config.exactBoost;
+        }
+        if (alias) {
+            score += config.aliasBoost;
+        }
+        candidates.push({
+            id,
+            score,
+            exact,
+            alias,
+            lexical,
+            fieldScores: lexicalMatch?.fieldScores ?? {},
+            matchedPhrases: [
+                ...(exactHits.get(id) ?? []),
+                ...(aliasHits.get(id) ?? []),
+            ],
+        });
+    }
+    candidates.sort(compareCandidates);
+    const trimmed = candidates.slice(0, config.candidateLimit);
+    const primary = [];
+    for (const candidate of trimmed.slice(0, config.resultLimit)) {
+        const entry = snapshot.entriesById.get(candidate.id);
+        if (entry) {
+            primary.push(entry);
+        }
+    }
+    const selectedIds = new Set(primary.map((entry) => entry.id));
+    const expanded = [];
+    for (const entry of primary) {
+        if (expanded.length >= config.relationLimit) {
+            break;
+        }
+        const relations = snapshot.relationIndex.get(entry.id) ?? [];
+        for (const relatedId of relations) {
+            if (expanded.length >= config.relationLimit) {
+                break;
+            }
+            if (selectedIds.has(relatedId)) {
+                continue;
+            }
+            const relatedEntry = snapshot.entriesById.get(relatedId);
+            if (!relatedEntry ||
+                !isAuthorized(relatedEntry, request, blockedDomains)) {
+                continue;
+            }
+            selectedIds.add(relatedId);
+            expanded.push(relatedEntry);
+        }
+    }
+    return {
+        primary,
+        expanded,
+        candidates: trimmed,
+        confidence: classifyConfidence(trimmed),
+        candidateCount: candidates.length,
+    };
+};
+//# sourceMappingURL=retrieval.js.map

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

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

package/dist/lib/neurolink.js

@@ -32,6 +32,7 @@ import { SYSTEM_LIMITS, DEFAULT_TOOL_ROUTING_TIMEOUT_MS, MIN_RECOVERY_TURN_BUDGE
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import { buildToolRoutingCatalog, buildRoutingQueryFromHistory, resolveToolRoutingExclusions, } from "./core/toolRouting.js";
 import { ToolRoutingCache } from "./core/toolRoutingCache.js";
+import { DEFAULT_RECENT_TURNS, KnowledgeGroundingEngine, } from "./knowledge/index.js";
 import { AIProviderFactory } from "./core/factory.js";
 import { createToolEventPayload } from "./core/toolEvents.js";
 import { ProviderRegistry } from "./factories/providerRegistry.js";
@@ -405,6 +406,9 @@ export class NeuroLink {
     // vectors are computed once. Cleared when the catalog changes via
     // setToolRoutingServers() so stale vectors are never reused.
     toolRoutingVectorCache;
+    // Knowledge grounding: lexical-first host-supplied retrieval engine. Built
+    // once from constructor config and undefined unless grounding is enabled.
+    knowledgeGroundingEngine;
     // Opt-in tool-signature deduplication config.
     toolDedupConfig;
     toolsConfig;
@@ -837,6 +841,18 @@ export class NeuroLink {
             // multiple NeuroLink instances.
             this.toolRoutingConfig = { ...config.toolRouting };
         }
+        const knowledgeGroundingConfig = config?.knowledgeGrounding;
+        if (knowledgeGroundingConfig?.enabled) {
+            if (Array.isArray(knowledgeGroundingConfig.sources) &&
+                knowledgeGroundingConfig.sources.length > 0) {
+                // The engine builds its immutable index asynchronously; eligible
+                // generate() and stream() calls await readiness before retrieval.
+                this.knowledgeGroundingEngine = new KnowledgeGroundingEngine(knowledgeGroundingConfig);
+            }
+            else {
+                logger.warn("[KnowledgeGrounding] enabled but no sources were provided; grounding disabled for this instance");
+            }
+        }
         if (config?.toolDedup) {
             this.toolDedupConfig = { ...config.toolDedup };
         }
@@ -853,7 +869,9 @@ export class NeuroLink {
         // generate() (marked so it never recursively re-routes). Fails open.
         this.classifierRouter = config?.classifierRouter?.enabled
             ? new ClassifierRouter(config.classifierRouter, {
-                generate: (genOptions) => this.generate(genOptions),
+                generate: (genOptions) => this.generate({
+                    ...genOptions,
+                }),
                 logger: {
                     debug: (message, meta) => logger.debug(message, meta),
                     warn: (message, meta) => logger.warn(message, meta),
@@ -3045,6 +3063,7 @@ Current user's request: ${currentInput}`;
      * @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
@@ -3131,9 +3150,22 @@ Current user's request: ${currentInput}`;
         if (typeof optionsOrPrompt !== "string") {
             optionsOrPrompt = cloneOptionsForCallIsolation(optionsOrPrompt);
         }
+        // Retrieve once at the public call boundary so fallback attempts reuse the
+        // same grounding block and internal preparation cannot inject it twice.
+        const groundingOptions = typeof optionsOrPrompt === "string"
+            ? { input: { text: optionsOrPrompt } }
+            : optionsOrPrompt;
+        const knowledgeOutcome = await this.retrieveKnowledgeGrounding(groundingOptions);
+        if (knowledgeOutcome?.ephemeralContext) {
+            const block = knowledgeOutcome.ephemeralContext.content;
+            optionsOrPrompt = {
+                ...groundingOptions,
+                systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(groundingOptions.systemPrompt, block),
+            };
+        }
         const startedAt = Date.now();
         try {
-            return await this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => {
+            const result = await this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => {
                 // Capture root-ness before startActiveSpan makes generateSpan active.
                 // The actual guest-rescue stamp is deferred to executeGenerateRequest,
                 // AFTER prepareGenerateRequest merges auth/requestContext-derived
@@ -3142,6 +3174,10 @@ Current user's request: ${currentInput}`;
                 const generateIsRoot = !trace.getSpan(context.active());
                 return tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(opts, generateSpan, generateIsRoot));
             });
+            if (knowledgeOutcome) {
+                result.knowledge = knowledgeOutcome.metadata;
+            }
+            return result;
         }
         catch (error) {
             // Lifecycle middleware (wrapGenerate.catch in builtin/lifecycle.ts)
@@ -5190,12 +5226,22 @@ Current user's request: ${currentInput}`;
             if (!generationContext) {
                 return null;
             }
+            // Provider construction runs BEFORE the budget check so runtime
+            // model-limit discovery (ensureModelLimits) can register real context
+            // windows first — ensureMCPGenerationBudget otherwise computes against
+            // the static default window (see directProviderGeneration for the
+            // lock-out this ordering prevents).
+            const provider = await AIProviderFactory.createProvider(generationContext.providerName, options.model, !options.disableTools, this, options.region, this.resolveCredentials(options.credentials));
+            provider.setTraceContext(this._metricsTraceContext);
+            // Never rejects — discovery failure degrades to static defaults.
+            await provider.ensureModelLimits?.();
             const conversationMessages = await this.ensureMCPGenerationBudget(options, requestId, generationContext.providerName, generationContext.enhancedSystemPrompt, generationContext.availableTools, generationContext.conversationMessages);
             return this.generateWithMCPProvider({
                 options,
                 requestId,
                 functionTag,
                 tryMCPStartTime,
+                provider,
                 providerName: generationContext.providerName,
                 availableTools: generationContext.availableTools,
                 enhancedSystemPrompt: generationContext.enhancedSystemPrompt,
@@ -5479,9 +5525,7 @@ Current user's request: ${currentInput}`;
         return compactedMessages;
     }
     async generateWithMCPProvider(context) {
-        const { options, requestId, functionTag, tryMCPStartTime, providerName, availableTools, enhancedSystemPrompt, conversationMessages, } = context;
-        const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, this, options.region, this.resolveCredentials(options.credentials));
-        provider.setTraceContext(this._metricsTraceContext);
+        const { options, requestId, functionTag, tryMCPStartTime, provider, providerName, availableTools, enhancedSystemPrompt, conversationMessages, } = context;
         this.emitter.emit("connected");
         this.emitter.emit("message", `${providerName} provider initialized successfully`);
         provider.setupToolExecutor({
@@ -5760,6 +5804,21 @@ Current user's request: ${currentInput}`;
                     ?.length
                     ? optionsWithMessages.conversationMessages
                     : await getConversationMessages(this.conversationMemory, options);
+                // Provider construction runs BEFORE the budget check so runtime
+                // model-limit discovery (ensureModelLimits) can register real
+                // context windows first. The previous order created a lock-out:
+                // checkContextBudget ran against the static default window, its
+                // pre-dispatch hard cap threw before the provider (whose
+                // constructor owns the discovery) ever existed — so a blocked call
+                // prevented the very discovery that would have unblocked it.
+                const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
+                this, // Pass SDK instance
+                options.region, // Pass region parameter
+                this.resolveCredentials(options.credentials));
+                // Propagate trace context for parent-child span hierarchy
+                provider.setTraceContext(this._metricsTraceContext);
+                // Never rejects — discovery failure degrades to static defaults.
+                await provider.ensureModelLimits?.();
                 // Pre-generation budget check
                 const budgetCheck = checkContextBudget({
                     provider: providerName,
@@ -5915,12 +5974,6 @@ Current user's request: ${currentInput}`;
                         }
                     }
                 }
-                const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
-                this, // Pass SDK instance
-                options.region, // Pass region parameter
-                this.resolveCredentials(options.credentials));
-                // Propagate trace context for parent-child span hierarchy
-                provider.setTraceContext(this._metricsTraceContext);
                 // ADD: Emit connection events for successful provider creation (Bedrock-compatible)
                 this.emitter.emit("connected");
                 this.emitter.emit("message", `${providerName} provider initialized successfully`);
@@ -6187,6 +6240,7 @@ Current user's request: ${currentInput}`;
      * @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
      *
@@ -6244,8 +6298,23 @@ Current user's request: ${currentInput}`;
         // top-level keys and left `options.input` shared with the caller.
         options = cloneOptionsForCallIsolation(options);
         const startedAt = Date.now();
+        // Retrieve once before provider/model fallback orchestration. Every fallback
+        // receives the same explicitly enriched options, without the retrieval helper
+        // mutating its input or injecting the same block more than once.
+        const knowledgeOutcome = await this.retrieveKnowledgeGrounding(options);
+        if (knowledgeOutcome?.ephemeralContext) {
+            const block = knowledgeOutcome.ephemeralContext.content;
+            options = {
+                ...options,
+                systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(options.systemPrompt, block),
+            };
+        }
         try {
-            return await this.streamWithIterationFallback(options);
+            const result = await this.streamWithIterationFallback(options);
+            if (knowledgeOutcome) {
+                result.knowledge = knowledgeOutcome.metadata;
+            }
+            return result;
         }
         catch (error) {
             // Mirror generate(): fire consumer onError for failures that
@@ -6913,6 +6982,63 @@ Current user's request: ${currentInput}`;
         // to recompute exclusions against the new server/tool set.
         this.toolRoutingCacheInstance = undefined;
     }
+    /** Knowledge-grounding engine health (null when it was not configured). */
+    getKnowledgeStatus() {
+        return this.knowledgeGroundingEngine?.getStatus() ?? null;
+    }
+    appendKnowledgeGroundingBlockToSystemPrompt(systemPrompt, block) {
+        if (typeof systemPrompt === "function") {
+            const originalSystemPrompt = systemPrompt;
+            return async (context) => {
+                const resolved = await resolveDynamicArgument(originalSystemPrompt, context);
+                return resolved.value ? `${resolved.value}\n\n${block}` : block;
+            };
+        }
+        return systemPrompt ? `${systemPrompt}\n\n${block}` : block;
+    }
+    /**
+     * 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.
+     */
+    async retrieveKnowledgeGrounding(options) {
+        const engine = this.knowledgeGroundingEngine;
+        if (!engine ||
+            !engine.isEnabled() ||
+            options.useKnowledgeGrounding !== true) {
+            return undefined;
+        }
+        const query = options.input?.text;
+        if (!query) {
+            return undefined;
+        }
+        try {
+            const conversationMessages = options.conversationMessages !== undefined
+                ? options.conversationMessages
+                : await this.fetchRecentRoutingHistory(options);
+            const recentTurns = conversationMessages
+                .filter((message) => message.role === "user" || message.role === "assistant")
+                .slice(-DEFAULT_RECENT_TURNS)
+                .map((message) => ({
+                role: message.role === "assistant"
+                    ? "assistant"
+                    : "user",
+                text: typeof message.content === "string" ? message.content : "",
+            }));
+            return await engine.ground({
+                query,
+                recentTurns,
+                scope: options.knowledgeContext,
+            });
+        }
+        catch (error) {
+            logger.warn("[KnowledgeGrounding] grounding hook failed open", {
+                error: String(error),
+            });
+            return undefined;
+        }
+    }
     async validateStreamRequestOptions(options, startTime) {
         await this.validateStreamInput(options);
         // Input validation for stream
@@ -7892,6 +8018,10 @@ Current user's request: ${currentInput}`;
         this, // Pass SDK instance
         options.region, // Pass region parameter
         this.resolveCredentials(options.credentials));
+        // Runtime model-limit discovery must land BEFORE the stream budget
+        // check below — otherwise it computes against the static default
+        // window. Never rejects; failure degrades to static defaults.
+        await provider.ensureModelLimits?.();
         // Propagate trace context for parent-child span hierarchy
         provider.setTraceContext(this._metricsTraceContext);
         // Enable tool execution for the provider using BaseProvider method