@juspay/neurolink 10.3.0 → 10.4.0

package/dist/providers/openaiChatCompletionsClient.js

@@ -14,8 +14,72 @@
  * module is to be the native replacement for the AI SDK's OpenAI wrapper.
  */
 import { createParser } from "eventsource-parser";
-import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
+import { sanitizeToolName } from "../mcp/toolConverter.js";
+import { convertZodToJsonSchema, normalizeWireToolSchema, } from "../utils/schemaConversion.js";
+import { estimateTokens, TOKENS_PER_MESSAGE, } from "../utils/tokenEstimation.js";
 export const stripTrailingSlash = (s) => s.replace(/\/+$/, "");
+// OpenAI-compatible wire tool names: first char letter/underscore (some
+// chat templates treat a leading digit or hyphen as invalid identifiers),
+// then letters/digits/underscore/hyphen, 64 chars total — exactly the
+// pattern below, which mirrors sanitizeToolName's output alphabet. MCP
+// servers can register names outside it (dots, colons, spaces); sent
+// verbatim they make backends reject the tools block or emit tool_calls
+// that no longer match the registry.
+const WIRE_TOOL_NAME_RE = /^[a-zA-Z_][a-zA-Z0-9_-]{0,63}$/;
+/**
+ * Build a bijective original ↔ wire tool-name map. Returns undefined when
+ * every name is already wire-valid (the common case — the wire then uses
+ * original names untouched and callers skip all mapping). Sanitized names
+ * that collide get a deterministic numeric suffix so the map stays
+ * invertible.
+ */
+export const buildWireToolNameMaps = (names) => {
+    if (names.every((name) => WIRE_TOOL_NAME_RE.test(name))) {
+        return undefined;
+    }
+    const toWire = new Map();
+    const fromWire = new Map();
+    for (const name of names) {
+        let wire = WIRE_TOOL_NAME_RE.test(name) ? name : sanitizeToolName(name);
+        if (fromWire.has(wire)) {
+            let suffix = 2;
+            let candidate;
+            do {
+                const tail = `_${suffix}`;
+                candidate = `${wire.slice(0, 64 - tail.length)}${tail}`;
+                suffix++;
+            } while (fromWire.has(candidate));
+            wire = candidate;
+        }
+        toWire.set(name, wire);
+        fromWire.set(wire, name);
+    }
+    return { toWire, fromWire };
+};
+/**
+ * Estimate the input-token cost of a fully-built wire request (messages +
+ * tool definitions). Used by the per-request max_tokens fit against a
+ * RUNTIME-DISCOVERED context window — deliberately the same char-based
+ * estimator the budget pipeline uses, so both layers agree.
+ */
+export const estimateWireTokens = (messages, tools, provider) => {
+    let total = 0;
+    for (const message of messages) {
+        const content = typeof message.content === "string"
+            ? message.content
+            : safeStringify(message.content);
+        total += estimateTokens(content, provider) + TOKENS_PER_MESSAGE;
+        // tool_calls only exists on the assistant variant of the message union.
+        const toolCalls = message.tool_calls;
+        if (toolCalls) {
+            total += estimateTokens(safeStringify(toolCalls), provider);
+        }
+    }
+    if (tools && tools.length > 0) {
+        total += estimateTokens(safeStringify(tools), provider);
+    }
+    return total;
+};
 export const safeStringify = (value) => {
     try {
         return JSON.stringify(value ?? "");
@@ -132,7 +196,7 @@ export const convertContentForOpenAI = (content) => {
     }
     return out;
 };
-export const messageBuilderToOpenAI = (messages) => {
+export const messageBuilderToOpenAI = (messages, toolNameToWire) => {
     const out = [];
     for (const msg of messages) {
         switch (msg.role) {
@@ -165,11 +229,14 @@ export const messageBuilderToOpenAI = (messages) => {
                         }
                         else if (p.type === "tool-call") {
                             const tc = part;
+                            // History tool-call names must match the wire `tools` block —
+                            // forward-map when a wire-name map is in effect.
+                            const historyName = tc.toolName ?? "";
                             toolCalls.push({
                                 id: tc.toolCallId ?? "",
                                 type: "function",
                                 function: {
-                                    name: tc.toolName ?? "",
+                                    name: toolNameToWire?.get(historyName) ?? historyName,
                                     arguments: stringifyToolInput(tc.input),
                                 },
                             });
@@ -223,7 +290,7 @@ export const messageBuilderToOpenAI = (messages) => {
     }
     return out;
 };
-export const buildToolsForOpenAI = (tools) => {
+export const buildToolsForOpenAI = (tools, toolNameToWire) => {
     const entries = Object.entries(tools);
     if (entries.length === 0) {
         return undefined;
@@ -235,14 +302,16 @@ export const buildToolsForOpenAI = (tools) => {
         // tool.inputSchema may be a Zod schema, an AI SDK jsonSchema() wrapper,
         // or plain JSON Schema — convertZodToJsonSchema normalizes all three.
         // Sending raw Zod internals (with `_def`) gets rejected by most
-        // OpenAI-compatible endpoints.
+        // OpenAI-compatible endpoints. normalizeWireToolSchema then strips
+        // $schema/$defs indirection that proxied backends render into chat
+        // templates verbatim (degrading argument generation).
         const parameters = rawSchema
-            ? convertZodToJsonSchema(rawSchema)
+            ? normalizeWireToolSchema(convertZodToJsonSchema(rawSchema))
             : { type: "object", properties: {} };
         out.push({
             type: "function",
             function: {
-                name,
+                name: toolNameToWire?.get(name) ?? name,
                 ...(t.description ? { description: t.description } : {}),
                 parameters,
             },
@@ -254,7 +323,7 @@ export const buildToolsForOpenAI = (tools) => {
 // path that BaseProvider's `generate()` still drives via the AI SDK's
 // `generateText`. The streaming path doesn't need these — it consumes
 // NeuroLink-shaped options directly.
-export const v3ToolsToOpenAI = (tools) => {
+export const v3ToolsToOpenAI = (tools, toolNameToWire) => {
     if (!tools || tools.length === 0) {
         return undefined;
     }
@@ -264,9 +333,12 @@ export const v3ToolsToOpenAI = (tools) => {
             out.push({
                 type: "function",
                 function: {
-                    name: t.name,
+                    name: toolNameToWire?.get(t.name) ?? t.name,
                     ...(t.description ? { description: t.description } : {}),
-                    parameters: t.inputSchema,
+                    // The AI SDK serializes inputSchema to JSON Schema before
+                    // doGenerate; normalize the wire form ($ref/$defs inlining,
+                    // annotation stripping, nullable collapse) for proxied backends.
+                    parameters: normalizeWireToolSchema(t.inputSchema),
                     ...(t.strict !== undefined ? { strict: t.strict } : {}),
                 },
             });
@@ -276,14 +348,19 @@ export const v3ToolsToOpenAI = (tools) => {
     }
     return out.length > 0 ? out : undefined;
 };
-export const v3ToolChoiceToOpenAI = (choice) => {
+export const v3ToolChoiceToOpenAI = (choice, toolNameToWire) => {
     switch (choice.type) {
         case "auto":
         case "none":
         case "required":
             return choice.type;
         case "tool":
-            return { type: "function", function: { name: choice.toolName } };
+            return {
+                type: "function",
+                function: {
+                    name: toolNameToWire?.get(choice.toolName) ?? choice.toolName,
+                },
+            };
     }
 };
 export const v3ResponseFormatToOpenAI = (rf) => {
@@ -303,7 +380,7 @@ export const v3ResponseFormatToOpenAI = (rf) => {
         },
     };
 };
-export const mapNeuroLinkToolChoice = (choice) => {
+export const mapNeuroLinkToolChoice = (choice, toolNameToWire) => {
     if (!choice) {
         return undefined;
     }
@@ -313,7 +390,10 @@ export const mapNeuroLinkToolChoice = (choice) => {
     if (typeof choice === "object" && choice !== null) {
         const c = choice;
         if (c.type === "tool" && c.toolName) {
-            return { type: "function", function: { name: c.toolName } };
+            return {
+                type: "function",
+                function: { name: toolNameToWire?.get(c.toolName) ?? c.toolName },
+            };
         }
     }
     return undefined;

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