@juspay/neurolink 5.2.0 → 5.3.0

package/dist/lib/telemetry/telemetry-service.js

@@ -4,6 +4,7 @@ import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentation
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 import { Resource } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
+import { logger } from "../utils/logger.js";
 export class TelemetryService {
     static instance;
     sdk;
@@ -25,7 +26,7 @@ export class TelemetryService {
             this.initializeTelemetry();
         }
         else {
-            console.log("[Telemetry] Disabled - set NEUROLINK_TELEMETRY_ENABLED=true or configure OTEL_EXPORTER_OTLP_ENDPOINT to enable");
+            logger.debug("[Telemetry] Disabled - set NEUROLINK_TELEMETRY_ENABLED=true or configure OTEL_EXPORTER_OTLP_ENDPOINT to enable");
         }
     }
     static getInstance() {
@@ -56,10 +57,10 @@ export class TelemetryService {
             this.meter = metrics.getMeter("neurolink-ai");
             this.tracer = trace.getTracer("neurolink-ai");
             this.initializeMetrics();
-            console.log("[Telemetry] Initialized with endpoint:", process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
+            logger.debug("[Telemetry] Initialized with endpoint:", process.env.OTEL_EXPORTER_OTLP_ENDPOINT);
         }
         catch (error) {
-            console.error("[Telemetry] Failed to initialize:", error);
+            logger.error("[Telemetry] Failed to initialize:", error);
             this.enabled = false;
         }
     }
@@ -95,10 +96,10 @@ export class TelemetryService {
         }
         try {
             await this.sdk?.start();
-            console.log("[Telemetry] SDK started successfully");
+            logger.debug("[Telemetry] SDK started successfully");
         }
         catch (error) {
-            console.error("[Telemetry] Failed to start SDK:", error);
+            logger.error("[Telemetry] Failed to start SDK:", error);
             this.enabled = false;
         }
     }
@@ -249,10 +250,10 @@ export class TelemetryService {
         if (this.enabled && this.sdk) {
             try {
                 await this.sdk.shutdown();
-                console.log("[Telemetry] SDK shutdown completed");
+                logger.debug("[Telemetry] SDK shutdown completed");
             }
             catch (error) {
-                console.error("[Telemetry] Error during shutdown:", error);
+                logger.error("[Telemetry] Error during shutdown:", error);
             }
         }
     }

package/dist/mcp/client.d.ts

@@ -33,6 +33,7 @@ export declare class NeuroLinkMCPClient extends EventEmitter {
      * Get all registered tools
      */
     getTools(): Record<string, {
+        name: string;
         description?: string;
         inputSchema?: unknown;
     }>;

package/dist/mcp/client.js

@@ -130,6 +130,7 @@ export class NeuroLinkMCPClient extends EventEmitter {
         const tools = {};
         for (const [name, tool] of this.tools) {
             tools[name] = {
+                name: name, // Include the tool name as a property
                 description: tool.description,
                 inputSchema: tool.inputSchema,
             };

package/dist/mcp/context-manager.d.ts

@@ -29,6 +29,7 @@ export interface ContextRequest {
 export declare class ContextManager {
     private sessionCounter;
     private activeContexts;
+    private static cachedLogger;
     /**
      * Create a new execution context with rich information
      *

package/dist/mcp/context-manager.js

@@ -10,6 +10,7 @@
 export class ContextManager {
     sessionCounter = 0;
     activeContexts = new Map();
+    static cachedLogger = null;
     /**
      * Create a new execution context with rich information
      *
@@ -64,6 +65,7 @@ export class ContextManager {
             },
             path: {
                 join: (...paths) => {
+                    // Use dynamic require for synchronous path operations
                     const path = require("path");
                     return path.join(...paths);
                 },
@@ -85,11 +87,13 @@ export class ContextManager {
                 },
             },
             grantedPermissions: request.permissions || [],
-            log: (level, message, data) => {
-                // Use logger if available, otherwise console
+            log: async (level, message, data) => {
+                // Use cached logger if available, otherwise import and cache
                 try {
-                    const { logger } = require("../utils/logger.js");
-                    logger[level](message, data);
+                    if (!ContextManager.cachedLogger) {
+                        ContextManager.cachedLogger = await import("../utils/logger.js").then(({ logger }) => logger);
+                    }
+                    ContextManager.cachedLogger[level](message, data);
                 }
                 catch {
                     console[level === "debug" ? "log" : level](message, data);

package/dist/mcp/function-calling.d.ts

@@ -14,6 +14,7 @@ export declare function mcpToolToAISDKTool(tool: NeuroLinkMCPTool, serverId: str
  */
 export declare function getAvailableFunctionTools(): Promise<{
     tools: Tool[];
+    toolsObject: Record<string, Tool>;
     toolMap: Map<string, {
         serverId: string;
         toolName: string;
@@ -49,3 +50,15 @@ export declare function getFunctionToolsForCategory(category?: string, maxTools?
  * Check if function calling is available
  */
 export declare function isFunctionCallingAvailable(): Promise<boolean>;
+/**
+ * Utility function to create a named tool object for debugging
+ */
+export declare function createNamedTool(name: string, toolDef: any): any & {
+    name: string;
+};
+/**
+ * Get tools with proper name properties for debugging
+ */
+export declare function getToolsWithNames(): Promise<Record<string, any & {
+    name: string;
+}>>;

package/dist/mcp/function-calling.js

@@ -8,6 +8,100 @@ import { z } from "zod";
 import { unifiedRegistry } from "./unified-registry.js";
 import { createExecutionContext } from "./context-manager.js";
 import { mcpLogger } from "./logging.js";
+/**
+ * Parses neurolink-specific function name patterns to extract the server ID and tool name.
+ *
+ * @param {string[]} parts - An array of strings representing parts of a function name,
+ * typically obtained by splitting the function name on underscores.
+ * @returns {{ serverId: string; toolName: string } | null} An object containing the `serverId`
+ * and `toolName` if the input matches a neurolink-specific pattern, or `null` if no match is found.
+ *
+ * @example
+ * // Returns { serverId: "neurolink_ai_core", toolName: "generate" }
+ * parseNeuroLinkPattern(["neurolink", "ai", "core", "generate"]);
+ *
+ * @example
+ * // Returns { serverId: "neurolink_utility", toolName: "format_number" }
+ * parseNeuroLinkPattern(["neurolink", "utility", "format_number"]);
+ *
+ * @example
+ * // Returns null
+ * parseNeuroLinkPattern(["other", "pattern"]);
+ */
+function parseNeuroLinkPattern(parts) {
+    if (parts.length >= 3 &&
+        parts[0] === "neurolink" &&
+        (parts[1] === "ai" || parts[1] === "utility")) {
+        // neurolink_ai_core_generate -> serverId: "neurolink_ai_core", toolName: "generate"
+        // neurolink_utility_format_number -> serverId: "neurolink_utility", toolName: "format_number"
+        if (parts[1] === "ai" && parts[2] === "core") {
+            return {
+                serverId: "neurolink_ai_core",
+                toolName: parts.slice(3).join("_"),
+            };
+        }
+        else if (parts[1] === "utility") {
+            return {
+                serverId: "neurolink_utility",
+                toolName: parts.slice(2).join("_"),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Parse underscore-separated function name format
+ */
+function parseUnderscoreFormat(functionName) {
+    const parts = functionName.split("_");
+    if (parts.length >= 2) {
+        // Try neurolink-specific patterns first
+        const neurolinkResult = parseNeuroLinkPattern(parts);
+        if (neurolinkResult) {
+            return neurolinkResult;
+        }
+        // Default underscore parsing
+        return {
+            serverId: parts[0],
+            toolName: parts.slice(1).join("_"),
+        };
+    }
+    return null;
+}
+/**
+ * Parse dot-separated function name format (legacy support)
+ */
+function parseDotFormat(functionName) {
+    const parts = functionName.split(".");
+    if (parts.length >= 2) {
+        return {
+            serverId: parts[0],
+            toolName: parts.slice(1).join("."),
+        };
+    }
+    return null;
+}
+/**
+ * Parse function name to extract server ID and tool name
+ * Handles various naming patterns including neurolink server patterns
+ */
+function parseFunctionName(functionName) {
+    // Try underscore format first (most common)
+    const underscoreResult = parseUnderscoreFormat(functionName);
+    if (underscoreResult) {
+        return underscoreResult;
+    }
+    // Fallback to dot format for backward compatibility
+    const dotResult = parseDotFormat(functionName);
+    if (dotResult) {
+        return dotResult;
+    }
+    // Final fallback - return as-is with unknown server
+    return {
+        serverId: "unknown",
+        toolName: functionName,
+    };
+}
 /**
  * Convert MCP tool to AI SDK function definition
  */
@@ -55,6 +149,7 @@ export function mcpToolToAISDKTool(tool, serverId) {
 export async function getAvailableFunctionTools() {
     const functionTag = "getAvailableFunctionTools";
     const tools = [];
+    const toolsObject = {};
     const toolMap = new Map();
     try {
         // Add overall timeout for the entire function
@@ -281,6 +376,8 @@ export async function getAvailableFunctionTools() {
                             },
                         });
                         tools.push(aiTool);
+                        // Store tool with proper name association
+                        toolsObject[functionName] = aiTool;
                         // Store mapping for execution - CRITICAL: Use sanitized functionName as key
                         toolMap.set(functionName, {
                             serverId: typeof toolInfo.serverId === "string"
@@ -302,7 +399,7 @@ export async function getAvailableFunctionTools() {
                 if (overallTimeoutId) {
                     clearTimeout(overallTimeoutId);
                 }
-                return { tools, toolMap };
+                return { tools, toolsObject, toolMap };
             }
             catch (error) {
                 if (overallTimeoutId) {
@@ -315,7 +412,7 @@ export async function getAvailableFunctionTools() {
     }
     catch (error) {
         mcpLogger.error(`[${functionTag}] Error getting function tools:`, error);
-        return { tools: [], toolMap: new Map() };
+        return { tools: [], toolsObject: {}, toolMap: new Map() };
     }
 }
 /**
@@ -345,38 +442,12 @@ export async function executeFunctionCall(functionName, parameters, context) {
             });
         }
         // Parse server and tool name from function name
-        // First try underscore format (sanitized), then fallback to dot format
-        let parts = functionName.split("_");
-        let serverId = "unknown";
-        let toolName = functionName;
-        if (parts.length >= 2) {
-            // Handle underscore format (sanitized names)
-            const firstPart = parts[0];
-            if (firstPart && typeof firstPart === "string" && firstPart.length > 0) {
-                serverId = firstPart;
-            }
-            else {
-                serverId = "unknown";
-            }
-            toolName = parts.slice(1).join("_"); // Rejoin in case tool name had underscores
-        }
-        else {
-            // Fallback to dot format for backward compatibility
-            parts = functionName.split(".");
-            if (parts.length === 2) {
-                const parsedServerId = parts[0];
-                const parsedToolName = parts[1];
-                if (parsedServerId && parsedToolName) {
-                    serverId = parsedServerId;
-                    toolName = parsedToolName;
-                }
-            }
-            else {
-                // Can't parse - try executing as-is through unified registry
-                mcpLogger.debug(`[${functionTag}] Cannot parse function name format: ${functionName}, trying unified registry`);
-                const result = await unifiedRegistry.executeTool(functionName, actualParameters, finalContext);
-                return result;
-            }
+        const { serverId, toolName } = parseFunctionName(functionName);
+        if (serverId === "unknown") {
+            // Can't parse - try executing as-is through unified registry
+            mcpLogger.debug(`[${functionTag}] Cannot parse function name format: ${functionName}, trying unified registry`);
+            const result = await unifiedRegistry.executeTool(functionName, actualParameters, finalContext);
+            return result;
         }
         // Handle built-in NeuroLink servers directly
         if (serverId === "neurolink-utility" ||
@@ -541,3 +612,31 @@ export async function isFunctionCallingAvailable() {
         return false;
     }
 }
+/**
+ * Utility function to create a named tool object for debugging
+ */
+export function createNamedTool(name, toolDef) {
+    return {
+        name,
+        description: toolDef.description,
+        parameters: toolDef.parameters,
+        execute: toolDef.execute,
+    };
+}
+/**
+ * Get tools with proper name properties for debugging
+ */
+export async function getToolsWithNames() {
+    try {
+        const { toolsObject } = await getAvailableFunctionTools();
+        const namedTools = {};
+        for (const [name, tool] of Object.entries(toolsObject)) {
+            namedTools[name] = createNamedTool(name, tool);
+        }
+        return namedTools;
+    }
+    catch (error) {
+        mcpLogger.warn("[getToolsWithNames] Failed to get tools with names:", error);
+        return {};
+    }
+}

package/dist/mcp/neurolink-mcp-client.d.ts

@@ -70,6 +70,7 @@ export declare class NeuroLinkMCPClient extends EventEmitter {
      * Get registered tools
      */
     getTools(): Record<string, {
+        name: string;
         description?: string;
         inputSchema?: unknown;
     }>;

package/dist/mcp/neurolink-mcp-client.js

@@ -244,11 +244,26 @@ Response (JSON array only):`;
                     exists: async () => false,
                 },
                 path: {
-                    join: (...paths) => require("path").join(...paths),
-                    resolve: (...paths) => require("path").resolve(...paths),
-                    relative: (from, to) => require("path").relative(from, to),
-                    dirname: (path) => require("path").dirname(path),
-                    basename: (path, ext) => require("path").basename(path, ext),
+                    join: (...paths) => {
+                        const pathModule = require("path");
+                        return pathModule.join(...paths);
+                    },
+                    resolve: (...paths) => {
+                        const pathModule = require("path");
+                        return pathModule.resolve(...paths);
+                    },
+                    relative: (from, to) => {
+                        const pathModule = require("path");
+                        return pathModule.relative(from, to);
+                    },
+                    dirname: (pathArg) => {
+                        const pathModule = require("path");
+                        return pathModule.dirname(pathArg);
+                    },
+                    basename: (pathArg, ext) => {
+                        const pathModule = require("path");
+                        return pathModule.basename(pathArg, ext);
+                    },
                 },
                 grantedPermissions: [],
                 log: console.log,
@@ -409,6 +424,7 @@ Please provide a natural response based on the tool results.`;
         const tools = {};
         for (const [name, tool] of this.tools) {
             tools[name] = {
+                name: name, // Include the tool name as a property
                 description: tool.description,
                 inputSchema: tool.inputSchema,
             };

package/dist/providers/function-calling-provider.d.ts

@@ -16,10 +16,15 @@ export declare class FunctionCallingProvider implements AIProvider {
     private enableFunctionCalling;
     private sessionId;
     private userId;
+    private cachedToolsObject;
+    private cachedToolMap;
+    private cacheTimestamp;
+    private readonly cacheExpiryMs;
     constructor(baseProvider: AIProvider, options?: {
         enableFunctionCalling?: boolean;
         sessionId?: string;
         userId?: string;
+        cacheExpiryMs?: number;
     });
     /**
      * PRIMARY METHOD: Stream content using AI (recommended for new code)
@@ -31,7 +36,11 @@ export declare class FunctionCallingProvider implements AIProvider {
      */
     generate(optionsOrPrompt: TextGenerationOptions | string, analysisSchema?: ZodType<unknown, ZodTypeDef, unknown> | Schema<unknown>): Promise<GenerateResult>;
     /**
-     * Generate text using AI SDK's native function calling
+     * Generate text with tools using the AI SDK's generate function (with tools object)
+     */
+    private generateWithToolsObject;
+    /**
+     * Generate text using AI SDK's native function calling (legacy array-based)
      */
     private generateWithTools;
     /**
@@ -44,7 +53,11 @@ export declare class FunctionCallingProvider implements AIProvider {
      */
     private sanitizeToolName;
     /**
-     * Convert our tools to AI SDK format with proper execution
+     * Wrap tools with proper execution context (for object-based tools)
+     */
+    private wrapToolsWithExecution;
+    /**
+     * Convert our tools to AI SDK format with proper execution (legacy array-based)
      */
     private convertToAISDKTools;
     /**
@@ -54,6 +67,53 @@ export declare class FunctionCallingProvider implements AIProvider {
     /**
      * Alias for generate() - CLI-SDK consistency
      */
+    /**
+     * Clear cached tools - Cache Invalidation Strategy
+     *
+     * WHEN TO CALL clearToolsCache():
+     *
+     * 1. **MCP Server Changes**: When MCP servers are added, removed, or restarted
+     *    - After calling unifiedRegistry.addServer() or removeServer()
+     *    - When MCP server configurations change
+     *    - After MCP server restart or reconnection
+     *
+     * 2. **Tool Registration Changes**: When custom tools are modified
+     *    - After registering new SDK tools via registerTool()
+     *    - When tool implementations change
+     *    - After unregistering tools
+     *
+     * 3. **Provider Reinitialization**: When the provider context changes
+     *    - Before switching between different AI providers
+     *    - When session context changes significantly
+     *    - After provider authentication refresh
+     *
+     * 4. **Error Recovery**: When tool execution encounters systematic failures
+     *    - After MCP connection errors are resolved
+     *    - When tool discovery needs to be re-run
+     *    - During error recovery workflows
+     *
+     * 5. **Development/Testing**: During development and testing cycles
+     *    - Between test cases that modify tool availability
+     *    - When testing different tool configurations
+     *    - During hot reloading scenarios
+     *
+     * CACHE LIFECYCLE:
+     * - Cache is populated on first generate() call via getAvailableFunctionTools()
+     * - Cache persists across multiple generate() calls for performance
+     * - Cache is invalidated by calling this method
+     * - Next generate() call will rebuild cache from current tool state
+     *
+     * PERFORMANCE IMPACT:
+     * - Clearing cache forces tool discovery on next usage (~100-500ms overhead)
+     * - Recommended to clear cache proactively rather than reactively
+     * - Consider batching tool changes before clearing cache
+     *
+     * THREAD SAFETY:
+     * - This method is not thread-safe
+     * - Avoid calling during active generate() operations
+     * - Safe to call between separate AI generation requests
+     */
+    clearToolsCache(): void;
     /**
      * Short alias for generate() - CLI-SDK consistency
      */
@@ -66,6 +126,7 @@ export declare function createFunctionCallingProvider(baseProvider: AIProvider,
     enableFunctionCalling?: boolean;
     sessionId?: string;
     userId?: string;
+    cacheExpiryMs?: number;
 }): AIProvider;
 /**
  * Enhanced MCP Provider Factory that creates function-calling enabled providers
@@ -77,4 +138,5 @@ export declare function createMCPAwareProviderV3(baseProvider: AIProvider, optio
     enableFunctionCalling?: boolean;
     sessionId?: string;
     userId?: string;
+    cacheExpiryMs?: number;
 }): AIProvider;