@juspay/neurolink 10.3.0 → 10.4.0

package/dist/lib/proxy/proxyFetch.d.ts

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

package/dist/lib/proxy/proxyFetch.js

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

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

@@ -13,6 +13,7 @@ import type { ModelPoolConfig } from "./modelPool.js";
 import type { RequestRouter } from "./requestRouter.js";
 import type { ClassifierRouterConfig } from "./classifierRouter.js";
 import type { SkillsConfig } from "./skills.js";
+import type { KnowledgeGroundingConfig } from "./knowledge.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -130,6 +131,17 @@ export type NeurolinkConstructorConfig = {
      * Opt-in and fails open on read paths. See {@link SkillsConfig}.
      */
     skills?: SkillsConfig;
+    /**
+     * Knowledge grounding: lexical-first host-supplied knowledge retrieval. When
+     * enabled with at least one source, a deterministic in-memory retrieval runs
+     * before each generate()/stream() turn — independently of tool routing — and
+     * attaches a token-bounded, ephemeral knowledge block to the model call. No
+     * embeddings or vector store. Opt-in (`enabled: false` by default) and fails
+     * open: any retrieval failure leaves the turn ungrounded. Sources are fixed
+     * for the lifetime of the instance. See
+     * {@link KnowledgeGroundingConfig}.
+     */
+    knowledgeGrounding?: KnowledgeGroundingConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.

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

@@ -429,7 +429,7 @@ export type SessionMetadata = {
  * Report type for agentic loop reports
  * Identifies the platform or category of the report
  */
-export type AgenticLoopReportType = "META" | "GOOGLEADS" | "GOOGLEGA4" | "OTHER";
+export type AgenticLoopReportType = "META" | "GOOGLEADS" | "GOOGLEGA4" | "SHOPIFY" | "BREEZE" | "OTHER";
 /**
  * Status of an agentic loop report
  */

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

@@ -7,6 +7,7 @@
  * @module types/dynamic
  */
 import type { AIProviderName } from "../constants/enums.js";
+import type { KnowledgeRequestScope } from "./knowledge.js";
 /**
  * Context passed to context-aware dynamic argument functions.
  * `requestContext` is whatever the consumer passed as `dynamicContext` —
@@ -39,6 +40,17 @@ export type DynamicArgument<T> = T | (() => T) | (() => Promise<T>) | ((context:
  * instead of static values for context-aware resolution.
  */
 export type DynamicOptions = {
+    /**
+     * Opt this call into the knowledge grounding configured on the NeuroLink
+     * instance. This flag is intentionally static because grounding runs before
+     * dynamic arguments are resolved.
+     */
+    useKnowledgeGrounding?: boolean;
+    /**
+     * Enabled integrations used to scope knowledge retrieval for this turn.
+     * This scope is intentionally static for the same reason.
+     */
+    knowledgeContext?: KnowledgeRequestScope;
     model?: DynamicArgument<string>;
     provider?: DynamicArgument<AIProviderName | string>;
     temperature?: DynamicArgument<number>;

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

@@ -1,5 +1,6 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { RAGConfig } from "./rag.js";
+import type { KnowledgeGroundingMetadata, KnowledgeRequestScope } from "./knowledge.js";
 import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, TokenUsage } from "./analytics.js";
 import type { JsonValue } from "./common.js";
@@ -323,8 +324,15 @@ export type GenerateOptions = {
      * never the step-cap text. Unset = no turn-level deadline (the library
      * imposes no product policy).
      *
-     * Enforced by the native Vertex loops (Gemini + Claude); AI-SDK-driven
-     * providers currently ignore it.
+     * Enforced by the native Vertex loops (Gemini + Claude) AND the AI-SDK
+     * loop path (litellm and other OpenAI-compatible providers). On the AI-SDK
+     * path, an explicit `timeout` also engages the same wrap-up when
+     * `turnTimeoutMs` is unset. Once the wrap-up window begins (see
+     * `wrapupTimeLeadMs`), the loop forcibly sets `toolChoice: "none"` for the
+     * remaining steps — overriding any caller-supplied `toolChoice` or
+     * `prepareStep` tool selection — and appends an honest time message that a
+     * caller's `prepareStep` callback does not observe (it runs before the
+     * wrap-up nudge is applied). An honest partial beats a discarded turn.
      */
     turnTimeoutMs?: number;
     /**
@@ -340,6 +348,11 @@ export type GenerateOptions = {
      * next tool-result turn telling the model to consolidate what it has and
      * produce its final answer. Defaults to 120_000 when `turnTimeoutMs` is
      * set; ignored when it is not.
+     *
+     * On the AI-SDK loop path the lead is clamped to a quarter of the turn
+     * budget (so short budgets don't wrap up on step one) and wrap-up steps
+     * run with a forced `toolChoice: "none"` — see `turnTimeoutMs` for the
+     * exact override semantics.
      */
     wrapupTimeLeadMs?: number;
     /**
@@ -350,6 +363,8 @@ export type GenerateOptions = {
     toolTimeoutMs?: number;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
+    /** Disable the schema-driven tool call repair mechanism (BZ-665). Default: false (repair enabled). */
+    disableToolCallRepair?: boolean;
     /**
      * Disable tool execution (including built-in tools)
      *
@@ -531,6 +546,17 @@ export type GenerateOptions = {
     onError?: OnErrorCallback;
     /** Pre-validated user context for the request */
     requestContext?: Record<string, unknown>;
+    /**
+     * Opt this generation 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;
     /** Raw auth token — validated by configured auth provider */
     auth?: {
         token: string;
@@ -676,6 +702,8 @@ export type GenerateStopReason = "completed" | "step-cap" | "context-cap" | "tim
  */
 export type GenerateResult = {
     content: string;
+    /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
+    knowledge?: KnowledgeGroundingMetadata;
     /**
      * Parsed structured object when a `schema` was requested. Populated from
      * AI-SDK experimental_output, or from text-mode coercion (balanced-scan +
@@ -1015,6 +1043,8 @@ export type TextGenerationOptions = {
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     disableTools?: boolean;
+    /** Disable the schema-driven tool call repair mechanism (BZ-665). Default: false (repair enabled). */
+    disableToolCallRepair?: boolean;
     maxSteps?: number;
     /** Include only these tools by name (whitelist). If set, only matching tools are available. */
     toolFilter?: string[];

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

@@ -28,6 +28,7 @@ export * from "./generate.js";
 export * from "./grounding.js";
 export * from "./guardrails.js";
 export * from "./hitl.js";
+export * from "./knowledge.js";
 export * from "./livekit.js";
 export * from "./mcp.js";
 export * from "./mcpOutput.js";

package/dist/lib/types/index.js

@@ -29,6 +29,7 @@ export * from "./generate.js";
 export * from "./grounding.js";
 export * from "./guardrails.js";
 export * from "./hitl.js";
+export * from "./knowledge.js";
 export * from "./livekit.js";
 export * from "./mcp.js";
 export * from "./mcpOutput.js";

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

@@ -0,0 +1,342 @@
+/**
+ * Knowledge grounding — lexical-first host-supplied knowledge retrieval.
+ *
+ * A host application owns a structured *knowledge registry*: versioned entries
+ * describing concepts, configuration, taxonomies, procedures, and operating
+ * rules. NeuroLink owns the
+ * generic engine that ingests that registry, builds an in-memory lexical
+ * index once per instance, and — independently of tool routing — retrieves a
+ * small, token-bounded set of relevant entries before each main model call.
+ * The selected entries are attached as *ephemeral context*: visible to the
+ * current generation call, never persisted into conversation memory.
+ *
+ * This is retrieval-augmented generation WITHOUT vector retrieval. The first
+ * release ranks with exact identifiers, reviewed aliases, metadata filters,
+ * and weighted field-aware BM25 only. No embedding model, embedding service,
+ * or vector store is initialized. An LLM reranker and semantic retrieval are
+ * deferred behind an explicit evaluation gate.
+ *
+ * Ownership boundary: NeuroLink defines the contracts below and the engine;
+ * it never contains host product content. The host supplies content and
+ * per-request scope. The engine stays provider-neutral.
+ *
+ * Type names are globally prefixed `Knowledge*` to satisfy the repo's
+ * unique-type-name rule and to avoid collision with the pre-existing
+ * web-search `grounding.ts` vocabulary (`EnhancedGroundingMetadata` et al.),
+ * which is a different concept (Google search grounding, not product
+ * knowledge).
+ */
+/** What a knowledge entry primarily is. Drives context labelling, not ranking. */
+export type KnowledgeEntryKind = "concept" | "text" | "configuration" | "tool" | "procedure" | "policy" | "troubleshooting";
+/** Lifecycle state. Only `active` entries are retrievable by default. */
+export type KnowledgeStatus = "draft" | "active" | "deprecated";
+/**
+ * Retrieval mode. Only `"lexical"` is supported in the first release; the
+ * literal is a union of one to reserve a clean upgrade path to `"hybrid"` /
+ * `"vector"` without a breaking change.
+ */
+export type KnowledgeRetrievalMode = "lexical";
+/**
+ * Confidence class returned with every retrieval so the host prompt can
+ * instruct the model to qualify low-confidence answers rather than present
+ * them as authoritative.
+ */
+export type KnowledgeRetrievalConfidence = "high" | "medium" | "low" | "none";
+/** The five weighted text fields used by the field-aware lexical scorer. */
+export type KnowledgeFieldName = "title" | "aliases" | "keywords" | "summary" | "body";
+/**
+ * The record a host author writes. `id`, `title`, `summary`, `domain`, and
+ * `integrations` are required; every other field is optional and omitted
+ * optionals fall back to SDK defaults during normalization.
+ */
+export type KnowledgeEntryInput = {
+    /** Stable unique id (e.g. "account.multi-step-flow"). Drives exact-match lookup and citations. */
+    id: string;
+    /** Human-readable name of the concept/setting. Highest-weighted search field. */
+    title: string;
+    /** One-line searchable description — the short answer when a full body is unnecessary. */
+    summary: string;
+    /** Primary grouping and the main retrieval filter (e.g. "account-settings"). */
+    domain: string;
+    /** Integration identifiers this entry applies to. Empty array = applies to all integrations. */
+    integrations: string[];
+    /** What the entry is (concept, configuration, procedure, …). Default "text". Labels context, not ranking. */
+    kind?: KnowledgeEntryKind;
+    /** Lifecycle state. Default "active"; only active entries are retrievable. */
+    status?: KnowledgeStatus;
+    /** Full explanatory content (Markdown). Use only when the summary is insufficient. */
+    body?: string;
+    /** Reviewed alternate phrasings or raw identifiers that resolve to exact and alias matches. */
+    aliases?: string[];
+    /** Extra search terms that aid recall but are not full aliases. */
+    keywords?: string[];
+    /** Ids of directly related entries, pulled in by bounded relationship expansion. */
+    relatedEntryIds?: string[];
+    /** Id of the parent entry when this is a subtype or child. */
+    parentEntryId?: string;
+};
+/**
+ * The complete, defaults-resolved record NeuroLink indexes and injects. Omitted
+ * optionals are materialized (arrays to `[]`, `body` to `""`, `kind` to "text",
+ * `status` to "active") so downstream code never re-checks the resolution chain.
+ * Field meanings mirror `KnowledgeEntryInput`.
+ */
+export type NormalizedKnowledgeEntry = {
+    id: string;
+    title: string;
+    summary: string;
+    domain: string;
+    integrations: string[];
+    kind: KnowledgeEntryKind;
+    status: KnowledgeStatus;
+    body: string;
+    aliases: string[];
+    keywords: string[];
+    relatedEntryIds: string[];
+    parentEntryId?: string;
+    /** Content version from the source/manifest; appears in citations as [KB:id@version]. */
+    version: string;
+};
+/** One catalog inside a build manifest — a source id and its entries. */
+export type KnowledgeManifestCatalog = {
+    id: string;
+    entries: KnowledgeEntryInput[];
+};
+/**
+ * The versioned build artifact a host emits at build time. NeuroLink can
+ * consume it directly (each catalog becomes a structured source) so hosts do
+ * not need to construct `KnowledgeSource[]` by hand.
+ */
+export type KnowledgeManifest = {
+    schemaVersion: string;
+    contentVersion: string;
+    generatedAt: string;
+    catalogs: KnowledgeManifestCatalog[];
+};
+/**
+ * A configured knowledge source: inline structured entries passed to the
+ * engine. Markdown/provider source kinds were intentionally dropped for now;
+ * re-introduce this as a discriminated union (with a `type` tag) if another
+ * source kind is needed later.
+ */
+export type KnowledgeSource = {
+    id: string;
+    version?: string;
+    entries: KnowledgeEntryInput[];
+};
+/**
+ * Relative weight applied to a lexical match in each field. Title/alias
+ * matches outrank body matches. Tunable through evaluation.
+ */
+export type KnowledgeFieldWeights = {
+    title: number;
+    aliases: number;
+    keywords: number;
+    summary: number;
+    body: number;
+};
+/** Lexical retrieval tuning. All fields optional; the engine supplies defaults. */
+export type KnowledgeRetrievalConfig = {
+    /** Retrieval mode. Default: "lexical". */
+    mode?: KnowledgeRetrievalMode;
+    /** How many scored candidates enter relationship expansion. Default: 24. */
+    candidateLimit?: number;
+    /** How many primary entries survive into the assembled context. Default: 8. */
+    resultLimit?: number;
+    /** Cap on relationship-expanded entries added after primary retrieval. Default: 4. */
+    relationLimit?: number;
+    /** Per-field BM25 weights. */
+    fieldWeights?: KnowledgeFieldWeights;
+    /** Additive boost for an exact entry-id / configuration-key match. Dominant. Default: 100. */
+    exactBoost?: number;
+    /** Additive boost for an exact reviewed-alias phrase match. Default: 60. */
+    aliasBoost?: number;
+};
+/** Ephemeral-context assembly limits. */
+export type KnowledgeContextConfig = {
+    /** Hard token budget for the assembled grounding block. Default: 4000. */
+    maxTokens?: number;
+    /** Emit `[KB:<id>@<version>]` citations. Default: true. */
+    includeCitations?: boolean;
+};
+/**
+ * Constructor-level configuration for knowledge grounding. Sources are fixed
+ * for the lifetime of a NeuroLink instance so the index can be built once.
+ */
+export type KnowledgeGroundingConfig = {
+    /** Master switch. Grounding runs only when true AND at least one source is loaded. */
+    enabled: boolean;
+    /**
+     * Knowledge sources used to build the instance's immutable in-memory index.
+     * Required alongside `enabled`; pass an empty array only when intentionally
+     * configuring no retrievable content.
+     */
+    sources: KnowledgeSource[];
+    /** Exclude these domains from retrieval. Empty/omitted means all domains are eligible. */
+    blockedDomains?: string[];
+    retrieval?: KnowledgeRetrievalConfig;
+    context?: KnowledgeContextConfig;
+    /** Hard ceiling for one grounding operation before it fails open. Default: 800ms. */
+    timeoutMs?: number;
+};
+/**
+ * Per-call scope the host attaches to `GenerateOptions` / `StreamOptions`.
+ * Supplies the enabled integrations for this turn only.
+ */
+export type KnowledgeRequestScope = {
+    /** Installed/enabled integrations used to filter integration-specific entries. */
+    enabledIntegrations?: string[];
+};
+/** One bounded recent conversation turn used to contextualize the query. */
+export type KnowledgeConversationTurn = {
+    role: "user" | "assistant";
+    text: string;
+};
+/**
+ * The fully-resolved retrieval request the engine builds internally from the
+ * user query, a bounded recent window, and host scope.
+ */
+export type KnowledgeRetrievalRequest = {
+    query: string;
+    recentTurns: KnowledgeConversationTurn[];
+    enabledIntegrations: string[];
+};
+/**
+ * The internal search document built from a normalized entry. `exactKeys` and
+ * `fields` hold pre-tokenized normalized text. Internal to NeuroLink.
+ */
+export type IndexedKnowledgeDocument = {
+    id: string;
+    /** Normalized whole-phrase keys for exact/alias resolution. */
+    exactKeys: string[];
+    /** Per-field normalized token arrays fed to the field-aware BM25 scorer. */
+    fields: {
+        title: string[];
+        aliases: string[];
+        keywords: string[];
+        summary: string[];
+        body: string[];
+    };
+};
+/** One lexical match with its per-field score breakdown, for tuning and traces. */
+export type KnowledgeLexicalMatch = {
+    id: string;
+    score: number;
+    fieldScores: Partial<Record<KnowledgeFieldName, number>>;
+};
+/**
+ * Structural contract of the field-aware lexical index held in a snapshot. A
+ * concrete class in the knowledge runtime module satisfies this shape; typing
+ * it structurally keeps this types file free of runtime imports.
+ */
+export type KnowledgeLexicalSearcher = {
+    search: (queryTokens: string[], topK: number, eligibleEntryIds?: ReadonlySet<string>) => KnowledgeLexicalMatch[];
+};
+/**
+ * Immutable, ready-to-query index built once at client construction. Sessions
+ * and turns search this snapshot; it is never mutated in place.
+ */
+export type KnowledgeIndexSnapshot = {
+    entriesById: Map<string, NormalizedKnowledgeEntry>;
+    /** Normalized entry id or title phrase -> entry ids. */
+    exactIndex: Map<string, Set<string>>;
+    /** Normalized reviewed alias phrase -> entry ids. */
+    aliasIndex: Map<string, Set<string>>;
+    /** Entry id -> directly related entry ids, for bounded expansion. */
+    relationIndex: Map<string, string[]>;
+    /** Field-aware BM25 over all documents. */
+    lexical: KnowledgeLexicalSearcher;
+    entryCount: number;
+};
+/** A stable citation to a specific knowledge entry version. */
+export type KnowledgeCitation = {
+    id: string;
+    version: string;
+};
+/**
+ * The result of one retrieval: the selected entries, the assembled ephemeral
+ * context string, a confidence class, and assembly diagnostics.
+ */
+export type KnowledgeRetrievalResult = {
+    entries: NormalizedKnowledgeEntry[];
+    assembledContext: string;
+    confidence: KnowledgeRetrievalConfidence;
+    citations: KnowledgeCitation[];
+    /** Ids of the primary (non-expanded) entries, in final order. */
+    selectedEntryIds: string[];
+    /** Ids added by bounded relationship expansion. */
+    expandedEntryIds: string[];
+    /** Candidates scored before truncation to the result limit. */
+    candidateCount: number;
+    /** Estimated token size of `assembledContext`. */
+    contextTokens: number;
+    /** True when any entry body was truncated or entries were dropped for budget. */
+    truncated: boolean;
+    durationMs: number;
+};
+/**
+ * A block of context assembled for a single generation call without becoming
+ * durable conversation. The NeuroLink call boundary injects its content into
+ * the effective system prompt and never persists it as a user message.
+ */
+export type EphemeralContext = {
+    content: string;
+    kind: "knowledge";
+    /** Host-supplied reviewed content is trusted reference data. */
+    trusted: boolean;
+    citations?: KnowledgeCitation[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Aggregate, content-free diagnostics attached to a generation/stream result
+ * so the host can evaluate retrieval without the SDK exposing entry bodies.
+ */
+export type KnowledgeGroundingMetadata = {
+    retrievalMode: KnowledgeRetrievalMode;
+    selectedIds: string[];
+    expandedIds: string[];
+    candidateCount: number;
+    contextTokens: number;
+    truncated: boolean;
+    durationMs: number;
+    confidence?: KnowledgeRetrievalConfidence;
+    /** Present when grounding failed open; names the failure class. */
+    failureReason?: string;
+};
+/** A single validation problem found while normalizing/indexing a source. */
+export type KnowledgeValidationIssue = {
+    level: "error" | "warning";
+    code: string;
+    message: string;
+    entryId?: string;
+    sourceId?: string;
+};
+/** Outcome of validating a set of sources before indexing. */
+export type KnowledgeValidationResult = {
+    ok: boolean;
+    issues: KnowledgeValidationIssue[];
+};
+/** Per-turn input to `KnowledgeGroundingEngine.ground()`. */
+export type KnowledgeGroundingInput = {
+    query: string;
+    recentTurns?: KnowledgeConversationTurn[];
+    scope?: KnowledgeRequestScope;
+};
+/**
+ * The engine's per-turn output: the ephemeral context to inject (null on
+ * no-match, when disabled, or on fail-open), the aggregate metadata for the
+ * result, and the full retrieval for host diagnostics.
+ */
+export type KnowledgeGroundingOutcome = {
+    ephemeralContext: EphemeralContext | null;
+    metadata: KnowledgeGroundingMetadata;
+    retrieval: KnowledgeRetrievalResult | null;
+};
+/** Snapshot of engine health for telemetry and host introspection. */
+export type KnowledgeEngineStatus = {
+    enabled: boolean;
+    ready: boolean;
+    entryCount: number;
+    lastError: string | null;
+    validationIssues: KnowledgeValidationIssue[];
+};

package/dist/lib/types/knowledge.js

@@ -0,0 +1,30 @@
+/**
+ * Knowledge grounding — lexical-first host-supplied knowledge retrieval.
+ *
+ * A host application owns a structured *knowledge registry*: versioned entries
+ * describing concepts, configuration, taxonomies, procedures, and operating
+ * rules. NeuroLink owns the
+ * generic engine that ingests that registry, builds an in-memory lexical
+ * index once per instance, and — independently of tool routing — retrieves a
+ * small, token-bounded set of relevant entries before each main model call.
+ * The selected entries are attached as *ephemeral context*: visible to the
+ * current generation call, never persisted into conversation memory.
+ *
+ * This is retrieval-augmented generation WITHOUT vector retrieval. The first
+ * release ranks with exact identifiers, reviewed aliases, metadata filters,
+ * and weighted field-aware BM25 only. No embedding model, embedding service,
+ * or vector store is initialized. An LLM reranker and semantic retrieval are
+ * deferred behind an explicit evaluation gate.
+ *
+ * Ownership boundary: NeuroLink defines the contracts below and the engine;
+ * it never contains host product content. The host supplies content and
+ * per-request scope. The engine stays provider-neutral.
+ *
+ * Type names are globally prefixed `Knowledge*` to satisfy the repo's
+ * unique-type-name rule and to avoid collision with the pre-existing
+ * web-search `grounding.ts` vocabulary (`EnhancedGroundingMetadata` et al.),
+ * which is a different concept (Google search grounding, not product
+ * knowledge).
+ */
+export {};
+//# sourceMappingURL=knowledge.js.map

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

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

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

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