@juspay/neurolink 7.6.0 → 7.7.0

package/dist/sdk/toolRegistration.js

@@ -11,6 +11,56 @@ import { logger } from "../utils/logger.js";
  */
 const envValue = parseInt(process.env.NEUROLINK_TOOL_DESCRIPTION_MAX_LENGTH || "200", 10);
 const DEFAULT_DESCRIPTION_MAX_LENGTH = Number.isInteger(envValue) && envValue > 0 ? envValue : 200;
+/**
+ * Enhanced validation configuration
+ */
+const VALIDATION_CONFIG = {
+    // Tool name constraints
+    NAME_MIN_LENGTH: 2,
+    NAME_MAX_LENGTH: 50,
+    // Description constraints
+    DESCRIPTION_MIN_LENGTH: 10,
+    DESCRIPTION_MAX_LENGTH: DEFAULT_DESCRIPTION_MAX_LENGTH,
+    // Reserved tool names that cannot be used
+    RESERVED_NAMES: new Set([
+        "system",
+        "internal",
+        "core",
+        "ai",
+        "assistant",
+        "help",
+        "debug",
+        "test",
+        "mock",
+        "default",
+        "config",
+        "admin",
+        "root",
+        "neurolink",
+    ]),
+    // Recommended tool name patterns
+    RECOMMENDED_PATTERNS: [
+        "get_data",
+        "fetch_info",
+        "calculate_value",
+        "send_message",
+        "create_item",
+        "update_record",
+        "delete_file",
+        "validate_input",
+    ],
+    // Pre-compiled regex patterns for performance optimization
+    COMPILED_PATTERN_REGEXES: [
+        "get_data",
+        "fetch_info",
+        "calculate_value",
+        "send_message",
+        "create_item",
+        "update_record",
+        "delete_file",
+        "validate_input",
+    ].map((pattern) => new RegExp(pattern.replace(/_/g, "[_-]"), "i")),
+};
 /**
  * Converts a SimpleTool to Vercel AI SDK format
  */
@@ -89,50 +139,147 @@ export function createTool(config) {
     return config;
 }
 /**
- * Helper to create a tool with typed parameters
+ * Helper to create a validated tool with suggested improvements
  */
-export function createTypedTool(config) {
-    return config;
+export function createValidatedTool(name, config, options = {}) {
+    const { strict = true, suggestions = true } = options;
+    try {
+        // Validate the tool
+        validateTool(name, config);
+        // Provide helpful suggestions if enabled
+        if (suggestions) {
+            provideToolSuggestions(name, config);
+        }
+        logger.debug(`Tool '${name}' created and validated successfully`);
+        return config;
+    }
+    catch (error) {
+        if (strict) {
+            throw error;
+        }
+        // Log warning but continue in non-strict mode
+        logger.warn(`Tool '${name}' validation failed in non-strict mode`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return config;
+    }
 }
 /**
- * Validate tool description length
+ * Provide helpful suggestions for tool improvement
  */
-function validateDescriptionLength(name, description) {
-    const maxDescriptionLength = Number.isInteger(DEFAULT_DESCRIPTION_MAX_LENGTH) &&
-        DEFAULT_DESCRIPTION_MAX_LENGTH > 0
-        ? DEFAULT_DESCRIPTION_MAX_LENGTH
-        : 200;
-    if (description.length > maxDescriptionLength) {
-        throw new Error(`Tool '${name}' description should be concise (max ${maxDescriptionLength} characters). ` +
-            `Current length: ${description.length}. ` +
-            `Consider shortening: "${description.substring(0, 50)}..."`);
+function provideToolSuggestions(name, tool) {
+    const suggestions = [];
+    // Check for common improvements
+    if (!tool.parameters) {
+        suggestions.push("Consider adding a parameters schema using Zod for better type safety and validation");
+    }
+    if (!tool.metadata?.category) {
+        suggestions.push("Adding a category in metadata helps organize tools: { metadata: { category: 'data' } }");
+    }
+    if (!tool.metadata?.version) {
+        suggestions.push("Adding a version helps track tool updates: { metadata: { version: '1.0.0' } }");
+    }
+    // Check description quality
+    const description = tool.description.toLowerCase();
+    if (!description.includes("return") && !description.includes("result")) {
+        suggestions.push("Consider describing what the tool returns for better AI understanding");
+    }
+    if (suggestions.length > 0) {
+        logger.debug(`Tool '${name}' suggestions for improvement:`, {
+            suggestions: suggestions.slice(0, 3), // Limit to avoid spam
+        });
     }
 }
 /**
- * Validate tool configuration with detailed error messages
+ * Helper to create a tool with typed parameters
  */
-export function validateTool(name, tool) {
-    // Validate tool name
+export function createTypedTool(config) {
+    return config;
+}
+/**
+ * Enhanced tool name validation
+ */
+function validateToolName(name) {
+    // Basic validation
     if (!name || typeof name !== "string" || name.trim() === "") {
         throw new Error(`Invalid tool name: must be a non-empty string. Received: ${name}`);
     }
-    // Validate tool name format (alphanumeric, hyphens, underscores only)
+    const trimmedName = name.trim();
+    // Length validation
+    if (trimmedName.length < VALIDATION_CONFIG.NAME_MIN_LENGTH) {
+        throw new Error(`Tool name too short: '${name}' (${trimmedName.length} chars). ` +
+            `Minimum length: ${VALIDATION_CONFIG.NAME_MIN_LENGTH} characters. ` +
+            `Example: 'get_data', 'send_email'`);
+    }
+    if (trimmedName.length > VALIDATION_CONFIG.NAME_MAX_LENGTH) {
+        throw new Error(`Tool name too long: '${name}' (${trimmedName.length} chars). ` +
+            `Maximum length: ${VALIDATION_CONFIG.NAME_MAX_LENGTH} characters. ` +
+            `Consider shortening: '${trimmedName.substring(0, 20)}...'`);
+    }
+    // Format validation (alphanumeric, hyphens, underscores only)
     const validNamePattern = /^[a-zA-Z0-9_-]+$/;
-    if (!validNamePattern.test(name)) {
+    if (!validNamePattern.test(trimmedName)) {
         throw new Error(`Invalid tool name format: '${name}'. Tool names must contain only alphanumeric characters, hyphens, and underscores. ` +
             `Examples: 'calculate-tax', 'get_weather', 'sendEmail123'`);
     }
-    // Validate tool object
-    if (!tool || typeof tool !== "object") {
-        throw new Error(`Tool '${name}' must be an object with description and execute properties. Received: ${typeof tool}`);
+    // Reserved name validation
+    if (VALIDATION_CONFIG.RESERVED_NAMES.has(trimmedName.toLowerCase())) {
+        throw new Error(`Tool name '${name}' is reserved and cannot be used. ` +
+            `Reserved names include: ${Array.from(VALIDATION_CONFIG.RESERVED_NAMES).slice(0, 5).join(", ")}... ` +
+            `Try variations like: '${trimmedName}_tool', 'custom_${trimmedName}', '${trimmedName}_helper'`);
+    }
+    // Naming convention suggestions using pre-compiled patterns for performance
+    const hasGoodPattern = VALIDATION_CONFIG.COMPILED_PATTERN_REGEXES.some((patternRegex) => {
+        return patternRegex.test(trimmedName);
+    });
+    if (!hasGoodPattern && trimmedName.length > 10) {
+        logger.debug(`Tool name '${name}' could follow recommended patterns for better clarity. ` +
+            `Consider patterns like: ${VALIDATION_CONFIG.RECOMMENDED_PATTERNS.slice(0, 4).join(", ")}`);
     }
-    // Validate description
-    if (!tool.description ||
-        typeof tool.description !== "string" ||
-        tool.description.trim() === "") {
+}
+/**
+ * Enhanced description validation
+ */
+function validateToolDescription(name, description) {
+    if (!description ||
+        typeof description !== "string" ||
+        description.trim() === "") {
         throw new Error(`Tool '${name}' must have a non-empty description string. ` +
             `Example: { description: "Calculates mathematical expressions", execute: async (params) => {...} }`);
     }
+    const trimmedDescription = description.trim();
+    // Length validation
+    if (trimmedDescription.length < VALIDATION_CONFIG.DESCRIPTION_MIN_LENGTH) {
+        throw new Error(`Tool '${name}' description too short: ${trimmedDescription.length} characters. ` +
+            `Minimum length: ${VALIDATION_CONFIG.DESCRIPTION_MIN_LENGTH} characters. ` +
+            `The description should clearly explain what the tool does and when to use it. ` +
+            `Example: "Fetches current weather data for a specified location using coordinates or city name"`);
+    }
+    if (trimmedDescription.length > VALIDATION_CONFIG.DESCRIPTION_MAX_LENGTH) {
+        throw new Error(`Tool '${name}' description too long: ${trimmedDescription.length} characters. ` +
+            `Maximum length: ${VALIDATION_CONFIG.DESCRIPTION_MAX_LENGTH} characters. ` +
+            `Current description: "${trimmedDescription.substring(0, 50)}..." ` +
+            `Try to be more concise while keeping the essential information.`);
+    }
+    // Quality suggestions
+    const hasActionWord = /^(get|fetch|calculate|send|create|update|delete|validate|process|generate|parse|convert)/i.test(trimmedDescription);
+    if (!hasActionWord) {
+        logger.debug(`Tool '${name}' description could start with an action word (get, fetch, calculate, etc.) for better clarity: "${trimmedDescription.substring(0, 30)}..."`);
+    }
+}
+/**
+ * Validate tool configuration with detailed error messages
+ */
+export function validateTool(name, tool) {
+    // Enhanced tool name validation
+    validateToolName(name);
+    // Validate tool object
+    if (!tool || typeof tool !== "object") {
+        throw new Error(`Tool '${name}' must be an object with description and execute properties. Received: ${typeof tool}. ` +
+            `Expected format: { description: "Tool description", execute: async (params) => { ... } }`);
+    }
+    // Enhanced description validation
+    validateToolDescription(name, tool.description);
     // Validate execute function with signature guidance
     if (typeof tool.execute !== "function") {
         throw new Error(`Tool '${name}' must have an execute function. ` +
@@ -181,6 +328,101 @@ export function validateTool(name, tool) {
             throw new Error(errorMessage);
         }
     }
-    // Validate description length for better UX
-    validateDescriptionLength(name, tool.description);
+    // Validate metadata if provided
+    if (tool.metadata) {
+        if (typeof tool.metadata !== "object" || Array.isArray(tool.metadata)) {
+            throw new Error(`Tool '${name}' metadata must be an object. Received: ${typeof tool.metadata}. ` +
+                `Example: { category: "data", version: "1.0.0", author: "team@company.com" }`);
+        }
+        // Validate metadata fields
+        if (tool.metadata.version && typeof tool.metadata.version !== "string") {
+            throw new Error(`Tool '${name}' metadata.version must be a string. Received: ${typeof tool.metadata.version}. ` +
+                `Example: "1.0.0", "2.1.3-beta"`);
+        }
+        if (tool.metadata.category && typeof tool.metadata.category !== "string") {
+            throw new Error(`Tool '${name}' metadata.category must be a string. Received: ${typeof tool.metadata.category}. ` +
+                `Example: "data", "communication", "utility"`);
+        }
+        if (tool.metadata.tags && !Array.isArray(tool.metadata.tags)) {
+            throw new Error(`Tool '${name}' metadata.tags must be an array of strings. Received: ${typeof tool.metadata.tags}. ` +
+                `Example: ["api", "external", "web"]`);
+        }
+    }
+    // Success feedback for debugging
+    logger.debug(`Tool '${name}' validation passed`, {
+        nameLength: name.length,
+        descriptionLength: tool.description.length,
+        hasParameters: !!tool.parameters,
+        hasMetadata: !!tool.metadata,
+    });
+}
+/**
+ * Utility to validate multiple tools at once
+ */
+export function validateTools(tools) {
+    const valid = [];
+    const invalid = [];
+    for (const [name, tool] of Object.entries(tools)) {
+        try {
+            validateTool(name, tool);
+            valid.push(name);
+        }
+        catch (error) {
+            invalid.push({
+                name,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    logger.debug(`Bulk validation completed`, {
+        validCount: valid.length,
+        invalidCount: invalid.length,
+        totalTools: Object.keys(tools).length,
+    });
+    return { valid, invalid };
+}
+/**
+ * Get validation configuration for external inspection
+ */
+export function getValidationConfig() {
+    return { ...VALIDATION_CONFIG };
+}
+/**
+ * Check if a tool name is available (not reserved)
+ */
+export function isToolNameAvailable(name) {
+    if (!name || typeof name !== "string") {
+        return false;
+    }
+    const trimmedName = name.trim().toLowerCase();
+    return (trimmedName.length >= VALIDATION_CONFIG.NAME_MIN_LENGTH &&
+        trimmedName.length <= VALIDATION_CONFIG.NAME_MAX_LENGTH &&
+        !VALIDATION_CONFIG.RESERVED_NAMES.has(trimmedName) &&
+        /^[a-zA-Z0-9_-]+$/.test(trimmedName));
+}
+/**
+ * Suggest alternative tool names if the provided name is invalid
+ */
+export function suggestToolNames(baseName) {
+    if (!baseName || typeof baseName !== "string") {
+        return VALIDATION_CONFIG.RECOMMENDED_PATTERNS.slice(0, 3);
+    }
+    const cleanBase = baseName.toLowerCase().replace(/[^a-z0-9]/g, "_");
+    const suggestions = [];
+    // Add suffixes if the name is reserved
+    if (VALIDATION_CONFIG.RESERVED_NAMES.has(cleanBase)) {
+        suggestions.push(`${cleanBase}_tool`, `custom_${cleanBase}`, `${cleanBase}_helper`);
+    }
+    // Add pattern-based suggestions
+    const patterns = ["get_", "fetch_", "create_", "update_"];
+    patterns.forEach((pattern) => {
+        if (!cleanBase.startsWith(pattern.slice(0, -1))) {
+            suggestions.push(`${pattern}${cleanBase}`);
+        }
+    });
+    // Add recommended patterns if no good suggestions
+    if (suggestions.length === 0) {
+        suggestions.push(...VALIDATION_CONFIG.RECOMMENDED_PATTERNS.slice(0, 3));
+    }
+    return suggestions.slice(0, 5); // Limit to 5 suggestions
 }

package/dist/telemetry/telemetryService.d.ts

@@ -19,6 +19,11 @@ export declare class TelemetryService {
     private mcpToolCalls?;
     private connectionCounter?;
     private responseTimeHistogram?;
+    private activeConnectionCount;
+    private errorCount;
+    private requestCount;
+    private totalResponseTime;
+    private responseTimeCount;
     private constructor();
     static getInstance(): TelemetryService;
     private isTelemetryEnabled;
@@ -30,6 +35,7 @@ export declare class TelemetryService {
     recordAIError(provider: string, error: Error): void;
     recordMCPToolCall(toolName: string, duration: number, success: boolean): void;
     recordConnection(type: "websocket" | "sse" | "http"): void;
+    recordConnectionClosed(type: "websocket" | "sse" | "http"): void;
     recordResponseTime(endpoint: string, method: string, duration: number): void;
     recordCustomMetric(name: string, value: number, labels?: Record<string, string>): void;
     recordCustomHistogram(name: string, value: number, labels?: Record<string, string>): void;

package/dist/telemetry/telemetryService.js

@@ -21,6 +21,12 @@ export class TelemetryService {
     mcpToolCalls;
     connectionCounter;
     responseTimeHistogram;
+    // Runtime metrics tracking
+    activeConnectionCount = 0;
+    errorCount = 0;
+    requestCount = 0;
+    totalResponseTime = 0;
+    responseTimeCount = 0;
     constructor() {
         // Check if telemetry is enabled
         this.enabled = this.isTelemetryEnabled();
@@ -135,6 +141,10 @@ export class TelemetryService {
     }
     // Metrics Recording (NO-OP when disabled)
     recordAIRequest(provider, model, tokens, duration) {
+        // Track runtime metrics
+        this.requestCount++;
+        this.totalResponseTime += duration;
+        this.responseTimeCount++;
         if (!this.enabled || !this.aiRequestCounter) {
             return;
         }
@@ -144,6 +154,8 @@ export class TelemetryService {
         this.aiTokensUsed?.add(tokens, labels);
     }
     recordAIError(provider, error) {
+        // Track runtime metrics
+        this.errorCount++;
         if (!this.enabled || !this.aiProviderErrors) {
             return;
         }
@@ -164,12 +176,29 @@ export class TelemetryService {
         });
     }
     recordConnection(type) {
+        // Track runtime metrics
+        this.activeConnectionCount++;
         if (!this.enabled || !this.connectionCounter) {
             return;
         }
         this.connectionCounter.add(1, { connection_type: type });
     }
+    recordConnectionClosed(type) {
+        // Track runtime metrics
+        this.activeConnectionCount = Math.max(0, this.activeConnectionCount - 1);
+        if (!this.enabled || !this.connectionCounter) {
+            return;
+        }
+        // Optionally record disconnection metrics if needed
+        this.connectionCounter.add(-1, {
+            connection_type: type,
+            event: "disconnect",
+        });
+    }
     recordResponseTime(endpoint, method, duration) {
+        // Track runtime metrics
+        this.totalResponseTime += duration;
+        this.responseTimeCount++;
         if (!this.enabled || !this.responseTimeHistogram) {
             return;
         }
@@ -201,13 +230,19 @@ export class TelemetryService {
     // Health Checks
     async getHealthMetrics() {
         const memoryUsage = process.memoryUsage();
+        // Calculate error rate as percentage of errors vs total requests
+        const errorRate = this.requestCount > 0 ? (this.errorCount / this.requestCount) * 100 : 0;
+        // Calculate average response time
+        const averageResponseTime = this.responseTimeCount > 0
+            ? this.totalResponseTime / this.responseTimeCount
+            : 0;
         return {
             timestamp: Date.now(),
             memoryUsage,
             uptime: process.uptime(),
-            activeConnections: 0, // Would need to be provided by calling code
-            errorRate: 0, // Would need to be calculated from metrics
-            averageResponseTime: 0, // Would need to be calculated from metrics
+            activeConnections: this.activeConnectionCount,
+            errorRate: Math.round(errorRate * 100) / 100, // Round to 2 decimal places
+            averageResponseTime: Math.round(averageResponseTime * 100) / 100, // Round to 2 decimal places
         };
     }
     // Telemetry Status

package/dist/types/contextTypes.d.ts

@@ -2,7 +2,7 @@
  * Context Types for NeuroLink - Factory Pattern Implementation
  * Provides type-safe context integration for AI generation
  */
-import { JsonObject } from "./common.js";
+import type { JsonObject } from "./common.js";
 /**
  * Base context interface for all AI operations
  */
@@ -26,7 +26,7 @@ export interface BaseContext {
 /**
  * Context integration mode types
  */
-export type ContextIntegrationMode = "prompt_prefix" | "prompt_suffix" | "system_prompt" | "metadata_only" | "structured_prompt" | "none";
+type ContextIntegrationMode = "prompt_prefix" | "prompt_suffix" | "system_prompt" | "metadata_only" | "structured_prompt" | "none";
 /**
  * Context configuration for AI generation
  */
@@ -41,7 +41,7 @@ export interface ContextConfig {
 /**
  * Context processing result
  */
-export interface ProcessedContext {
+interface ProcessedContext {
     originalContext: BaseContext;
     processedContext: string | null;
     config: ContextConfig;
@@ -52,10 +52,58 @@ export interface ProcessedContext {
         mode: ContextIntegrationMode;
     };
 }
+/**
+ * Configuration for framework fields exclusion
+ * Can be customized per application or environment
+ */
+export interface FrameworkFieldsConfig {
+    defaultFields: string[];
+    additionalFields?: string[];
+    overrideFields?: string[];
+    includeFields?: string[];
+}
 /**
  * Factory for context processing
  */
 export declare class ContextFactory {
+    /**
+     * Default framework fields configuration
+     */
+    static readonly DEFAULT_FRAMEWORK_FIELDS: FrameworkFieldsConfig;
+    /**
+     * Current framework fields configuration
+     */
+    private static frameworkFieldsConfig;
+    /**
+     * Flag to track if framework fields have been initialized
+     */
+    private static isFrameworkFieldsInitialized;
+    /**
+     * Configure framework fields for exclusion from custom data
+     */
+    static configureFrameworkFields(config: Partial<FrameworkFieldsConfig>): void;
+    /**
+     * Get current framework fields configuration
+     * Ensures lazy initialization if not already loaded
+     */
+    static getFrameworkFieldsConfig(): FrameworkFieldsConfig;
+    /**
+     * Reset framework fields configuration to default
+     */
+    static resetFrameworkFieldsConfig(): void;
+    /**
+     * Load framework fields configuration from environment variables
+     * Supports NEUROLINK_CONTEXT_EXCLUDE_FIELDS and NEUROLINK_CONTEXT_INCLUDE_FIELDS
+     */
+    static loadFrameworkFieldsFromEnv(): void;
+    /**
+     * Add additional fields to exclude
+     */
+    static addFrameworkFieldsToExclude(fields: string[]): void;
+    /**
+     * Add fields to include (override exclusion)
+     */
+    static addFrameworkFieldsToInclude(fields: string[]): void;
     /**
      * Default context configuration
      */
@@ -98,13 +146,29 @@ export declare class ContextFactory {
     static extractEvaluationContext(context: BaseContext): JsonObject;
 }
 /**
- * Type guard to check if value is valid context
+ * Context conversion utilities for domain-specific data
+ * Replaces hardcoded business context with generic domain context
  */
-export declare function isValidContext(value: unknown): value is BaseContext;
-/**
- * Context integration options for AI generation
- */
-export interface ContextIntegrationOptions {
-    context?: BaseContext;
-    contextConfig?: Partial<ContextConfig>;
+import type { ExecutionContext } from "../mcp/contracts/mcpContract.js";
+interface ContextConversionOptions {
+    preserveLegacyFields?: boolean;
+    validateDomainData?: boolean;
+    includeMetadata?: boolean;
+}
+export declare class ContextConverter {
+    /**
+     * Convert legacy business context to generic domain context
+     * Based on business context patterns
+     */
+    static convertBusinessContext(legacyContext: Record<string, unknown>, domainType: string, options?: ContextConversionOptions): ExecutionContext;
+    /**
+     * Create execution context for any domain
+     */
+    static createDomainContext(domainType: string, domainData: Record<string, unknown>, sessionInfo?: {
+        sessionId?: string;
+        userId?: string;
+    }): ExecutionContext;
+    private static inferProvider;
+    private static extractCustomData;
 }
+export {};