@juspay/neurolink 9.14.0 → 9.16.0

package/dist/mcp/toolRegistry.js

@@ -10,6 +10,7 @@ import { directAgentTools } from "../agent/directTools.js";
 import { detectCategory, createMCPServerInfo } from "../utils/mcpDefaults.js";
 import { FlexibleToolValidator } from "./flexibleToolValidator.js";
 import { HITLUserRejectedError, HITLTimeoutError } from "../hitl/hitlErrors.js";
+import { withSpan, tracers, ATTR } from "../telemetry/index.js";
 export class MCPToolRegistry extends MCPRegistry {
     tools = new Map();
     toolImplementations = new Map(); // Store actual tool implementations
@@ -227,149 +228,218 @@ export class MCPToolRegistry extends MCPRegistry {
      */
     async executeTool(toolName, args, context) {
         const startTime = Date.now();
-        try {
-            registryLogger.info(`🔧 [TOOL_EXECUTION] Starting execution: ${toolName}`, { args, context });
-            // Try to find the tool by fully-qualified name first
-            let tool = this.tools.get(toolName);
-            registryLogger.info(`🔍 [TOOL_LOOKUP] Direct lookup result for '${toolName}':`, !!tool);
-            // If not found, search for tool by name across all entries (for backward compatibility)
-            let toolId = toolName;
-            if (!tool) {
-                for (const [candidateToolId, toolInfo] of this.tools.entries()) {
-                    if (toolInfo.name === toolName) {
+        // Resolve serverId eagerly for span attributes
+        let preResolvedServerId;
+        const toolEntry = this.tools.get(toolName);
+        if (toolEntry) {
+            preResolvedServerId = toolEntry.serverId;
+        }
+        else {
+            for (const toolInfo of this.tools.values()) {
+                if (toolInfo.name === toolName) {
+                    preResolvedServerId = toolInfo.serverId;
+                    break;
+                }
+            }
+        }
+        return withSpan({
+            name: "neurolink.tool.execute",
+            tracer: tracers.mcp,
+            attributes: {
+                [ATTR.GEN_AI_TOOL_NAME]: toolName,
+                [ATTR.MCP_SERVER_ID]: preResolvedServerId || "builtin",
+            },
+        }, async (span) => {
+            try {
+                registryLogger.info(`🔧 [TOOL_EXECUTION] Starting execution: ${toolName}`, {
+                    hasArgs: args !== undefined,
+                    hasContext: context !== undefined,
+                    sessionId: context?.sessionId,
+                });
+                // Try to find the tool by fully-qualified name first
+                let tool = this.tools.get(toolName);
+                registryLogger.info(`🔍 [TOOL_LOOKUP] Direct lookup result for '${toolName}':`, !!tool);
+                // If not found, search for tool by name across all entries (for backward compatibility)
+                let toolId = toolName;
+                if (!tool) {
+                    const matches = Array.from(this.tools.entries()).filter(([, toolInfo]) => toolInfo.name === toolName);
+                    if (matches.length > 1) {
+                        throw new Error(`Ambiguous tool name '${toolName}'. Use fully-qualified name 'serverId.${toolName}'.`);
+                    }
+                    if (matches.length === 1) {
+                        const [candidateToolId, toolInfo] = matches[0];
                         tool = toolInfo;
                         toolId = candidateToolId;
-                        break;
                     }
                 }
-            }
-            if (!tool) {
-                throw new Error(`Tool '${toolName}' not found in registry`);
-            }
-            // Create execution context if not provided
-            const execContext = {
-                sessionId: context?.sessionId || randomUUID(),
-                userId: context?.userId,
-                ...context,
-            };
-            // Get the tool implementation using the resolved toolId
-            const toolImpl = this.toolImplementations.get(toolId);
-            registryLogger.debug(`Looking for tool '${toolName}' (toolId: '${toolId}'), found: ${!!toolImpl}, type: ${typeof toolImpl?.execute}`);
-            registryLogger.debug(`Available tools:`, Array.from(this.toolImplementations.keys()));
-            if (!toolImpl || typeof toolImpl?.execute !== "function") {
-                throw new Error(`Tool '${toolName}' implementation not found or not executable`);
-            }
-            // HITL Safety Check: Request confirmation if required
-            let finalArgs = args;
-            if (this.hitlManager && this.hitlManager.isEnabled()) {
-                const requiresConfirmation = this.hitlManager.requiresConfirmation(toolName, args);
-                if (requiresConfirmation) {
-                    registryLogger.info(`Tool '${toolName}' requires HITL confirmation`);
-                    try {
-                        const confirmationResult = await this.hitlManager.requestConfirmation(toolName, args, {
-                            serverId: tool.serverId,
-                            sessionId: execContext.sessionId,
-                            userId: execContext.userId,
-                        });
-                        if (!confirmationResult.approved) {
-                            // User rejected the tool execution
-                            throw new HITLUserRejectedError(`Tool execution rejected by user: ${confirmationResult.reason || "No reason provided"}`, toolName, confirmationResult.reason);
+                if (!tool) {
+                    throw new Error(`Tool '${toolName}' not found in registry`);
+                }
+                // Classify tool type for observability
+                const serverId = tool.serverId || "unknown";
+                const toolType = serverId === "direct"
+                    ? "builtin"
+                    : serverId.startsWith("custom-tool-")
+                        ? "custom"
+                        : "mcp";
+                span.setAttribute("tool.type", toolType);
+                span.setAttribute(ATTR.MCP_SERVER_ID, serverId);
+                // Create execution context if not provided
+                const execContext = {
+                    ...context,
+                    sessionId: context?.sessionId ?? randomUUID(),
+                    userId: context?.userId,
+                };
+                // Get the tool implementation using the resolved toolId
+                const toolImpl = this.toolImplementations.get(toolId);
+                registryLogger.debug(`Looking for tool '${toolName}' (toolId: '${toolId}'), found: ${!!toolImpl}, type: ${typeof toolImpl?.execute}`);
+                registryLogger.debug(`Available tools:`, Array.from(this.toolImplementations.keys()));
+                if (!toolImpl || typeof toolImpl?.execute !== "function") {
+                    throw new Error(`Tool '${toolName}' implementation not found or not executable`);
+                }
+                // Capture argument metadata (avoid logging raw values which may contain secrets)
+                let argsStr;
+                try {
+                    argsStr = JSON.stringify(args).slice(0, 4096);
+                }
+                catch {
+                    argsStr = "[unserializable]";
+                }
+                span.setAttribute("tool.arguments_present", args !== undefined);
+                span.setAttribute("tool.arguments_size", argsStr.length);
+                // HITL Safety Check: Request confirmation if required
+                let finalArgs = args;
+                if (this.hitlManager && this.hitlManager.isEnabled()) {
+                    const requiresConfirmation = this.hitlManager.requiresConfirmation(toolName, args);
+                    if (requiresConfirmation) {
+                        registryLogger.info(`Tool '${toolName}' requires HITL confirmation`);
+                        span.addEvent("tool.hitl_requested");
+                        try {
+                            const confirmationResult = await this.hitlManager.requestConfirmation(toolName, args, {
+                                serverId: tool.serverId,
+                                sessionId: execContext.sessionId,
+                                userId: execContext.userId,
+                            });
+                            if (!confirmationResult.approved) {
+                                // User rejected the tool execution
+                                span.addEvent("tool.hitl_rejected");
+                                throw new HITLUserRejectedError(`Tool execution rejected by user: ${confirmationResult.reason || "No reason provided"}`, toolName, confirmationResult.reason);
+                            }
+                            span.addEvent("tool.hitl_approved");
+                            // User approved - use modified arguments if provided
+                            if (confirmationResult.modifiedArguments !== undefined) {
+                                finalArgs = confirmationResult.modifiedArguments;
+                                registryLogger.info(`Tool '${toolName}' arguments modified by user`);
+                            }
+                            registryLogger.info(`Tool '${toolName}' approved for execution (response time: ${confirmationResult.responseTime}ms)`);
                         }
-                        // User approved - use modified arguments if provided
-                        if (confirmationResult.modifiedArguments !== undefined) {
-                            finalArgs = confirmationResult.modifiedArguments;
-                            registryLogger.info(`Tool '${toolName}' arguments modified by user`);
+                        catch (error) {
+                            if (error instanceof HITLTimeoutError) {
+                                // Timeout occurred - user didn't respond in time
+                                registryLogger.warn(`Tool '${toolName}' execution timed out waiting for user confirmation`);
+                                throw error;
+                            }
+                            else if (error instanceof HITLUserRejectedError) {
+                                // User explicitly rejected
+                                registryLogger.info(`Tool '${toolName}' execution rejected by user`);
+                                throw error;
+                            }
+                            else {
+                                // Other HITL error (configuration, system error, etc.)
+                                registryLogger.error(`HITL confirmation failed for tool '${toolName}':`, error);
+                                throw new Error(`HITL confirmation failed: ${error instanceof Error ? error.message : String(error)}`);
+                            }
                         }
-                        registryLogger.info(`Tool '${toolName}' approved for execution (response time: ${confirmationResult.responseTime}ms)`);
                     }
-                    catch (error) {
-                        if (error instanceof HITLTimeoutError) {
-                            // Timeout occurred - user didn't respond in time
-                            registryLogger.warn(`Tool '${toolName}' execution timed out waiting for user confirmation`);
-                            throw error;
-                        }
-                        else if (error instanceof HITLUserRejectedError) {
-                            // User explicitly rejected
-                            registryLogger.info(`Tool '${toolName}' execution rejected by user`);
-                            throw error;
-                        }
-                        else {
-                            // Other HITL error (configuration, system error, etc.)
-                            registryLogger.error(`HITL confirmation failed for tool '${toolName}':`, error);
-                            throw new Error(`HITL confirmation failed: ${error instanceof Error ? error.message : String(error)}`);
-                        }
+                    else {
+                        registryLogger.debug(`Tool '${toolName}' does not require HITL confirmation`);
                     }
                 }
+                // Execute the actual tool (with potentially modified arguments)
+                registryLogger.debug(`Executing tool '${toolName}' with args:`, finalArgs);
+                const toolResult = await toolImpl.execute(finalArgs, execContext);
+                // Properly wrap raw results in ToolResult format
+                let result;
+                // Check if result is already a ToolResult object
+                if (toolResult &&
+                    typeof toolResult === "object" &&
+                    "success" in toolResult &&
+                    typeof toolResult.success === "boolean") {
+                    // Result is already a ToolResult, enhance with metadata
+                    const toolResultObj = toolResult;
+                    result = {
+                        ...toolResultObj,
+                        usage: {
+                            ...(toolResultObj.usage || {}),
+                            executionTime: Date.now() - startTime,
+                        },
+                        metadata: {
+                            ...(toolResultObj.metadata || {}),
+                            toolName,
+                            serverId: tool.serverId,
+                            sessionId: execContext.sessionId,
+                            executionTime: Date.now() - startTime,
+                        },
+                    };
+                }
                 else {
-                    registryLogger.debug(`Tool '${toolName}' does not require HITL confirmation`);
+                    // Result is a raw value, wrap it in ToolResult format
+                    result = {
+                        success: true,
+                        data: toolResult,
+                        usage: {
+                            executionTime: Date.now() - startTime,
+                        },
+                        metadata: {
+                            toolName,
+                            serverId: tool.serverId,
+                            sessionId: execContext.sessionId,
+                            executionTime: Date.now() - startTime,
+                        },
+                    };
                 }
+                // Update statistics
+                const duration = Date.now() - startTime;
+                this.updateStats(toolName, duration);
+                // Record success on span
+                let resultStr;
+                try {
+                    resultStr = JSON.stringify(result.data);
+                }
+                catch {
+                    resultStr = "[unserializable]";
+                }
+                span.setAttribute("tool.result_length", resultStr.length);
+                span.setAttribute("tool.success", true);
+                registryLogger.debug(`Tool '${toolName}' executed successfully in ${duration}ms`);
+                return result;
             }
-            // Execute the actual tool (with potentially modified arguments)
-            registryLogger.debug(`Executing tool '${toolName}' with args:`, finalArgs);
-            const toolResult = await toolImpl.execute(finalArgs, execContext);
-            // Properly wrap raw results in ToolResult format
-            let result;
-            // Check if result is already a ToolResult object
-            if (toolResult &&
-                typeof toolResult === "object" &&
-                "success" in toolResult &&
-                typeof toolResult.success === "boolean") {
-                // Result is already a ToolResult, enhance with metadata
-                const toolResultObj = toolResult;
-                result = {
-                    ...toolResultObj,
-                    usage: {
-                        ...(toolResultObj.usage || {}),
-                        executionTime: Date.now() - startTime,
-                    },
-                    metadata: {
-                        ...(toolResultObj.metadata || {}),
-                        toolName,
-                        serverId: tool.serverId,
-                        sessionId: execContext.sessionId,
-                        executionTime: Date.now() - startTime,
-                    },
-                };
-            }
-            else {
-                // Result is a raw value, wrap it in ToolResult format
-                result = {
-                    success: true,
-                    data: toolResult,
+            catch (error) {
+                registryLogger.error(`Tool execution failed: ${toolName}`, error);
+                // Record failure on span
+                span.setAttribute("tool.success", false);
+                // Rethrow precondition errors (tool not found, not executable)
+                const errMsg = error instanceof Error ? error.message : String(error);
+                if (errMsg.includes("not found in registry") ||
+                    errMsg.includes("not executable")) {
+                    throw error;
+                }
+                // Return runtime execution errors in ToolResult format
+                const errorResult = {
+                    success: false,
+                    data: null,
+                    error: error instanceof Error ? error.message : String(error),
                     usage: {
                         executionTime: Date.now() - startTime,
                     },
                     metadata: {
                         toolName,
-                        serverId: tool.serverId,
-                        sessionId: execContext.sessionId,
-                        executionTime: Date.now() - startTime,
+                        sessionId: context?.sessionId,
                     },
                 };
+                return errorResult;
             }
-            // Update statistics
-            const duration = Date.now() - startTime;
-            this.updateStats(toolName, duration);
-            registryLogger.debug(`Tool '${toolName}' executed successfully in ${duration}ms`);
-            return result;
-        }
-        catch (error) {
-            registryLogger.error(`Tool execution failed: ${toolName}`, error);
-            // Return error in ToolResult format
-            const errorResult = {
-                success: false,
-                data: null,
-                error: error instanceof Error ? error.message : String(error),
-                usage: {
-                    executionTime: Date.now() - startTime,
-                },
-                metadata: {
-                    toolName,
-                    sessionId: context?.sessionId,
-                },
-            };
-            return errorResult;
-        }
+        });
     }
     async listTools(filterOrContext) {
         // FIXED: Return unique tools (avoid duplicates from dual registration)

package/dist/models/anthropicModels.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Anthropic Models - Subscription Tier Access and Capabilities
+ *
+ * This module defines Anthropic Claude models, their availability by subscription tier,
+ * model capabilities, and provides helper functions for tier-based access control.
+ */
+import type { ClaudeSubscriptionTier, AnthropicModelMetadata } from "../types/subscriptionTypes.js";
+import { ModelAccessError } from "../types/errors.js";
+export type { ClaudeSubscriptionTier, AnthropicModelMetadata };
+export { ModelAccessError };
+/**
+ * Anthropic Claude model identifiers
+ *
+ * @description Enum of all available Claude models with their exact API identifiers.
+ * Models are organized by family (Haiku, Sonnet, Opus) and version.
+ */
+export declare enum AnthropicModel {
+    CLAUDE_3_HAIKU = "claude-3-haiku-20240307",
+    CLAUDE_3_5_HAIKU = "claude-3-5-haiku-20241022",
+    CLAUDE_3_5_SONNET = "claude-3-5-sonnet-20241022",
+    CLAUDE_3_5_SONNET_V2 = "claude-3-5-sonnet-v2-20241022",
+    CLAUDE_SONNET_4 = "claude-sonnet-4-20250514",
+    CLAUDE_3_OPUS = "claude-3-opus-20240229",
+    CLAUDE_OPUS_4 = "claude-opus-4-20250514"
+}
+/**
+ * Model access mapping by subscription tier
+ *
+ * Each tier includes progressively more models:
+ * - free: Basic models for casual use (Haiku only)
+ * - pro: Professional tier with Sonnet models
+ * - max: All models including the latest flagship Opus
+ * - api: Full API access to all models (based on API access)
+ */
+export declare const MODEL_TIER_ACCESS: Record<ClaudeSubscriptionTier, string[]>;
+/**
+ * Model metadata by model ID
+ *
+ * Comprehensive mapping of each Anthropic model's metadata,
+ * including display names, context windows, vision support, and extended thinking.
+ */
+export declare const MODEL_METADATA: Record<string, AnthropicModelMetadata>;
+/**
+ * Default model for each subscription tier
+ *
+ * These are the recommended default models that provide the best
+ * balance of capability and cost for each tier level.
+ */
+export declare const DEFAULT_MODELS_BY_TIER: Record<ClaudeSubscriptionTier, string>;
+/**
+ * Check if a model is available for a given subscription tier
+ *
+ * @param model - The model ID to check (can be enum value or string)
+ * @param tier - The subscription tier to check against
+ * @returns true if the model is available for the tier
+ *
+ * @example
+ * ```typescript
+ * if (isModelAvailableForTier(AnthropicModel.CLAUDE_OPUS_4, "pro")) {
+ *   // Model not available for pro tier
+ * }
+ *
+ * if (isModelAvailableForTier(AnthropicModel.CLAUDE_OPUS_4, "max")) {
+ *   // Model available for max tier
+ * }
+ * ```
+ */
+export declare function isModelAvailableForTier(model: string, tier: ClaudeSubscriptionTier): boolean;
+/**
+ * Get all models available for a given subscription tier
+ *
+ * @param tier - The subscription tier
+ * @returns Array of model IDs available for the tier
+ *
+ * @example
+ * ```typescript
+ * const models = getAvailableModelsForTier("pro");
+ * console.log(models);
+ * // ["claude-3-haiku-20240307", "claude-3-5-haiku-20241022", "claude-3-5-sonnet-20241022", ...]
+ * ```
+ */
+export declare function getAvailableModelsForTier(tier: ClaudeSubscriptionTier): string[];
+/**
+ * Get the human-readable display name for a model
+ *
+ * @param model - The model ID
+ * @returns The display name, or the model ID if not found
+ *
+ * @example
+ * ```typescript
+ * const name = getModelDisplayName(AnthropicModel.CLAUDE_OPUS_4);
+ * console.log(name); // "Claude Opus 4"
+ *
+ * const unknown = getModelDisplayName("unknown-model");
+ * console.log(unknown); // "unknown-model"
+ * ```
+ */
+export declare function getModelDisplayName(model: string): string;
+/**
+ * Get the default/recommended model for a given subscription tier
+ *
+ * Returns the best default model that should be used for each tier.
+ *
+ * @param tier - The subscription tier
+ * @returns The default model ID for the tier
+ *
+ * @example
+ * ```typescript
+ * const model = getDefaultModelForTier("max");
+ * console.log(model); // "claude-opus-4-20250514"
+ *
+ * const proModel = getDefaultModelForTier("pro");
+ * console.log(proModel); // "claude-sonnet-4-20250514"
+ * ```
+ */
+export declare function getDefaultModelForTier(tier: ClaudeSubscriptionTier): string;
+/**
+ * Get metadata for a specific model
+ *
+ * @param model - The model ID
+ * @returns The model metadata, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const metadata = getModelMetadata(AnthropicModel.CLAUDE_OPUS_4);
+ * if (metadata?.supportsExtendedThinking) {
+ *   // Enable extended thinking mode
+ * }
+ * ```
+ */
+export declare function getModelMetadata(model: string): AnthropicModelMetadata | undefined;
+/**
+ * Check if a model supports a specific capability
+ *
+ * @param model - The model ID
+ * @param capability - The capability to check
+ * @returns true if the model supports the capability
+ *
+ * @example
+ * ```typescript
+ * if (modelSupportsCapability(AnthropicModel.CLAUDE_OPUS_4, "supportsExtendedThinking")) {
+ *   // Use extended thinking
+ * }
+ * ```
+ */
+export declare function modelSupportsCapability(model: string, capability: keyof Omit<AnthropicModelMetadata, "displayName" | "description" | "family">): boolean;
+/**
+ * Get the minimum subscription tier required for a model
+ *
+ * @param model - The model ID to check
+ * @returns The minimum tier required, or "api" if model not found
+ *
+ * @example
+ * ```typescript
+ * const tier = getMinimumTierForModel(AnthropicModel.CLAUDE_OPUS_4);
+ * console.log(tier); // "max"
+ *
+ * const haikuTier = getMinimumTierForModel(AnthropicModel.CLAUDE_3_HAIKU);
+ * console.log(haikuTier); // "free"
+ * ```
+ */
+export declare function getMinimumTierForModel(model: string): ClaudeSubscriptionTier;
+/**
+ * Get all models that support a specific capability
+ *
+ * @param capability - The capability to filter by
+ * @returns Array of model IDs that have the capability
+ *
+ * @example
+ * ```typescript
+ * const thinkingModels = getModelsWithCapability("supportsExtendedThinking");
+ * console.log(thinkingModels);
+ * // ["claude-sonnet-4-20250514", "claude-opus-4-20250514"]
+ * ```
+ */
+export declare function getModelsWithCapability(capability: keyof Omit<AnthropicModelMetadata, "displayName" | "description" | "family">): string[];
+/**
+ * Get models filtered by family (haiku, sonnet, opus)
+ *
+ * @param family - The model family to filter by
+ * @returns Array of model IDs in the specified family
+ *
+ * @example
+ * ```typescript
+ * const opusModels = getModelsByFamily("opus");
+ * // ["claude-3-opus-20240229", "claude-opus-4-20250514"]
+ * ```
+ */
+export declare function getModelsByFamily(family: AnthropicModelMetadata["family"]): string[];
+/**
+ * Get the latest (non-deprecated) model in each family
+ *
+ * @returns Object mapping family name to the latest model in that family
+ *
+ * @example
+ * ```typescript
+ * const latest = getLatestModelsByFamily();
+ * console.log(latest.opus); // "claude-opus-4-20250514"
+ * console.log(latest.sonnet); // "claude-sonnet-4-20250514"
+ * ```
+ */
+export declare function getLatestModelsByFamily(): Record<AnthropicModelMetadata["family"], string | undefined>;
+/**
+ * Validate that a model is accessible for a given tier, throwing if not
+ *
+ * @param model - The model ID to validate
+ * @param tier - The subscription tier to validate against
+ * @throws {ModelAccessError} If the model is not available for the tier
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   validateModelAccess(AnthropicModel.CLAUDE_OPUS_4, "free");
+ * } catch (error) {
+ *   if (error instanceof ModelAccessError) {
+ *     console.log(`Upgrade to ${error.requiredTier} to use this model`);
+ *   }
+ * }
+ * ```
+ */
+export declare function validateModelAccess(model: string, tier: ClaudeSubscriptionTier): void;
+/**
+ * Compare subscription tiers
+ *
+ * @param tier1 - First tier to compare
+ * @param tier2 - Second tier to compare
+ * @returns Negative if tier1 < tier2, positive if tier1 > tier2, 0 if equal
+ */
+export declare function compareTiers(tier1: ClaudeSubscriptionTier, tier2: ClaudeSubscriptionTier): number;
+/**
+ * Get context window size for a model
+ *
+ * @param model - The model ID
+ * @returns The context window size in tokens, or 0 if model not found
+ */
+export declare function getContextWindow(model: string): number;
+/**
+ * Get max output tokens for a model
+ *
+ * @param model - The model ID
+ * @returns The max output tokens, or 0 if model not found
+ */
+export declare function getMaxOutputTokens(model: string): number;
+/**
+ * Check if a model supports vision/image input
+ *
+ * @param model - The model ID
+ * @returns true if the model supports vision
+ */
+export declare function supportsVision(model: string): boolean;
+/**
+ * Check if a model supports extended thinking
+ *
+ * @param model - The model ID
+ * @returns true if the model supports extended thinking
+ */
+export declare function supportsExtendedThinking(model: string): boolean;
+/**
+ * Alias for getDefaultModelForTier for backward compatibility
+ * @deprecated Use getDefaultModelForTier instead
+ */
+export declare const getRecommendedModelForTier: typeof getDefaultModelForTier;
+/**
+ * Alias for getModelMetadata for backward compatibility
+ * @deprecated Use getModelMetadata instead
+ */
+export declare const getModelCapabilities: typeof getModelMetadata;