@juspay/neurolink 9.41.0 → 9.42.1

package/dist/lib/utils/providerHealth.js

@@ -72,7 +72,7 @@ export class ProviderHealthChecker {
         };
         try {
             // 1. Check environment configuration
-            await this.checkEnvironmentConfiguration(providerName, healthStatus);
+            await this.checkEnvironmentConfiguration(providerName, healthStatus, timeout);
             // 2. Check API key validity (basic format validation)
             await this.checkApiKeyValidity(providerName, healthStatus);
             // 3. Optional: Connectivity test
@@ -129,7 +129,7 @@ export class ProviderHealthChecker {
     /**
      * Check environment configuration for a provider
      */
-    static async checkEnvironmentConfiguration(providerName, healthStatus) {
+    static async checkEnvironmentConfiguration(providerName, healthStatus, timeout) {
         const requiredEnvVars = this.getRequiredEnvironmentVariables(providerName);
         logger.debug(`[ProviderHealthChecker] Checking environment configuration for ${providerName}`, {
             requiredEnvVars,
@@ -160,7 +160,7 @@ export class ProviderHealthChecker {
             healthStatus.recommendations.push(`Set the following environment variables: ${missingVars.join(", ")}`);
         }
         // Provider-specific configuration checks
-        await this.checkProviderSpecificConfig(providerName, healthStatus);
+        await this.checkProviderSpecificConfig(providerName, healthStatus, timeout);
     }
     /**
      * Check API key validity (format validation)
@@ -228,7 +228,8 @@ export class ProviderHealthChecker {
         }
         // Providers that don't use API keys directly
         if (providerName === AIProviderName.OLLAMA ||
-            providerName === AIProviderName.BEDROCK) {
+            providerName === AIProviderName.BEDROCK ||
+            providerName === AIProviderName.LITELLM) {
             healthStatus.hasApiKey = true;
             return;
         }
@@ -260,30 +261,34 @@ export class ProviderHealthChecker {
             healthStatus.warning = "No connectivity test available for this provider";
             return;
         }
+        const headers = {
+            "User-Agent": "NeuroLink-HealthCheck/1.0",
+            ...this.getConnectivityHeaders(providerName),
+        };
         try {
             const controller = new AbortController();
             const timeoutId = setTimeout(() => controller.abort(), timeout);
-            const proxyFetch = createProxyFetch();
-            let response = await proxyFetch(endpoint, {
-                method: "HEAD",
-                signal: controller.signal,
-                headers: {
-                    "User-Agent": "NeuroLink-HealthCheck/1.0",
-                },
-            });
-            // Fallback to GET if HEAD returns 405 (Method Not Allowed) for restrictive gateways
-            if (response.status === 405) {
-                response = await proxyFetch(endpoint, {
-                    method: "GET",
+            try {
+                const proxyFetch = createProxyFetch();
+                let response = await proxyFetch(endpoint, {
+                    method: "HEAD",
                     signal: controller.signal,
-                    headers: {
-                        "User-Agent": "NeuroLink-HealthCheck/1.0",
-                    },
+                    headers,
                 });
+                // Fallback to GET if HEAD returns 405 (Method Not Allowed) for restrictive gateways
+                if (response.status === 405) {
+                    response = await proxyFetch(endpoint, {
+                        method: "GET",
+                        signal: controller.signal,
+                        headers,
+                    });
+                }
+                if (!response.ok) {
+                    healthStatus.configurationIssues.push(`Connectivity test failed: HTTP ${response.status}`);
+                }
             }
-            clearTimeout(timeoutId);
-            if (!response.ok) {
-                healthStatus.configurationIssues.push(`Connectivity test failed: HTTP ${response.status}`);
+            finally {
+                clearTimeout(timeoutId);
             }
         }
         catch (error) {
@@ -319,6 +324,14 @@ export class ProviderHealthChecker {
             }
         }
     }
+    static getConnectivityHeaders(providerName) {
+        if (providerName === AIProviderName.LITELLM) {
+            return {
+                Authorization: `Bearer ${process.env.LITELLM_API_KEY || "sk-anything"}`,
+            };
+        }
+        return {};
+    }
     /**
      * Check model availability (if possible without making API calls)
      */
@@ -368,6 +381,8 @@ export class ProviderHealthChecker {
                 return [];
             case AIProviderName.AZURE:
                 return ["AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"];
+            case AIProviderName.LITELLM:
+                return [];
             case AIProviderName.OLLAMA:
                 return []; // Ollama typically doesn't require API keys
             default:
@@ -391,8 +406,10 @@ export class ProviderHealthChecker {
                 return "AWS_ACCESS_KEY_ID";
             case AIProviderName.AZURE:
                 return "AZURE_OPENAI_API_KEY";
+            case AIProviderName.LITELLM:
+                return "LITELLM_API_KEY";
             case AIProviderName.OLLAMA:
-                return "OLLAMA_API_BASE";
+                return "OLLAMA_BASE_URL";
             default:
                 return "";
         }
@@ -416,6 +433,8 @@ export class ProviderHealthChecker {
                 return apiKey.length >= API_KEY_LENGTHS.AWS_ACCESS_KEY; // AWS access key length
             case AIProviderName.AZURE:
                 return apiKey.length >= API_KEY_LENGTHS.AZURE_MIN; // Azure OpenAI API key length
+            case AIProviderName.LITELLM:
+                return apiKey.length > 0;
             case AIProviderName.OLLAMA:
                 return true; // Ollama usually doesn't require specific format
             default:
@@ -437,8 +456,10 @@ export class ProviderHealthChecker {
                 return null; // Complex authentication required
             case AIProviderName.BEDROCK:
                 return null; // AWS endpoints vary by region
+            case AIProviderName.LITELLM:
+                return this.getLiteLLMModelsUrl();
             case AIProviderName.OLLAMA:
-                return "http://localhost:11434/api/version";
+                return this.getOllamaTagsUrl();
             default:
                 return null;
         }
@@ -446,7 +467,7 @@ export class ProviderHealthChecker {
     /**
      * Provider-specific configuration checks
      */
-    static async checkProviderSpecificConfig(providerName, healthStatus) {
+    static async checkProviderSpecificConfig(providerName, healthStatus, timeout) {
         switch (providerName) {
             case AIProviderName.VERTEX:
                 await this.checkVertexAIConfig(healthStatus);
@@ -457,8 +478,11 @@ export class ProviderHealthChecker {
             case AIProviderName.AZURE:
                 await this.checkAzureConfig(healthStatus);
                 break;
+            case AIProviderName.LITELLM:
+                await this.checkLiteLLMConfig(healthStatus, timeout);
+                break;
             case AIProviderName.OLLAMA:
-                await this.checkOllamaConfig(healthStatus);
+                await this.checkOllamaConfig(healthStatus, timeout);
                 break;
         }
     }
@@ -648,15 +672,180 @@ export class ProviderHealthChecker {
             healthStatus.recommendations.push("Set one of: AZURE_OPENAI_MODEL, AZURE_OPENAI_DEPLOYMENT, or AZURE_OPENAI_DEPLOYMENT_ID");
         }
     }
+    static getLiteLLMBaseUrl() {
+        return process.env.LITELLM_BASE_URL || "http://localhost:4000";
+    }
+    static getLiteLLMModelsUrl() {
+        return new URL("/v1/models", this.getLiteLLMBaseUrl()).toString();
+    }
+    static getConfiguredLiteLLMModel() {
+        return process.env.LITELLM_MODEL || "openai/gpt-4o-mini";
+    }
+    static getOllamaBaseUrl() {
+        return (process.env.OLLAMA_BASE_URL ||
+            process.env.OLLAMA_API_BASE ||
+            "http://localhost:11434");
+    }
+    static getOllamaTagsUrl() {
+        return new URL("/api/tags", this.getOllamaBaseUrl()).toString();
+    }
+    static getConfiguredOllamaModel() {
+        return process.env.OLLAMA_MODEL || "llama3.1:8b";
+    }
+    static async fetchJsonWithTimeout(url, options = {}) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), options.timeout ?? this.DEFAULT_TIMEOUT);
+        try {
+            const proxyFetch = createProxyFetch();
+            const response = await proxyFetch(url, {
+                method: "GET",
+                headers: options.headers,
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            return await response.json();
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+    static normalizeModelList(models) {
+        return models
+            .map((entry) => {
+            if (typeof entry === "string") {
+                return entry;
+            }
+            if (entry &&
+                typeof entry === "object" &&
+                "id" in entry &&
+                typeof entry.id === "string") {
+                return entry.id;
+            }
+            if (entry &&
+                typeof entry === "object" &&
+                "name" in entry &&
+                typeof entry.name === "string") {
+                return entry.name;
+            }
+            return null;
+        })
+            .filter((model) => typeof model === "string");
+    }
+    static hasRequestedModel(availableModels, requestedModel) {
+        const normalizedRequestedModel = requestedModel.trim();
+        const requiresExactMatch = /@/.test(normalizedRequestedModel);
+        return availableModels.some((model) => model === normalizedRequestedModel ||
+            (!requiresExactMatch &&
+                (model.startsWith(`${normalizedRequestedModel}:`) ||
+                    model.startsWith(`${normalizedRequestedModel}@`))));
+    }
+    static async getOllamaAvailableModels(timeout = 2000) {
+        const payload = (await this.fetchJsonWithTimeout(this.getOllamaTagsUrl(), {
+            timeout,
+        }));
+        return this.normalizeModelList(payload.models ?? []);
+    }
+    static async getLiteLLMAvailableModels(timeout = 2000) {
+        const payload = (await this.fetchJsonWithTimeout(this.getLiteLLMModelsUrl(), {
+            timeout,
+            headers: {
+                Authorization: `Bearer ${process.env.LITELLM_API_KEY || "sk-anything"}`,
+                "Content-Type": "application/json",
+            },
+        }));
+        return this.normalizeModelList(payload.data ?? []);
+    }
+    static async checkOllamaAvailability(options) {
+        try {
+            const models = await this.getOllamaAvailableModels(options.timeout);
+            if (!this.hasRequestedModel(models, options.model)) {
+                return {
+                    available: false,
+                    reason: `Configured Ollama model '${options.model}' is not installed`,
+                    models,
+                };
+            }
+            return { available: true, models };
+        }
+        catch (error) {
+            return {
+                available: false,
+                reason: error instanceof Error ? error.message : String(error),
+                models: [],
+            };
+        }
+    }
+    static async checkLiteLLMAvailability(options) {
+        try {
+            const models = await this.getLiteLLMAvailableModels(options.timeout);
+            if (models.length === 0) {
+                return {
+                    available: false,
+                    reason: "LiteLLM returned an empty model list",
+                    models,
+                };
+            }
+            if (!this.hasRequestedModel(models, options.model)) {
+                return {
+                    available: false,
+                    reason: `Configured LiteLLM model '${options.model}' is not exposed by the proxy`,
+                    models,
+                };
+            }
+            return { available: true, models };
+        }
+        catch (error) {
+            return {
+                available: false,
+                reason: error instanceof Error ? error.message : String(error),
+                models: [],
+            };
+        }
+    }
+    static async checkLiteLLMConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT) {
+        const liteLLMBase = this.getLiteLLMBaseUrl();
+        if (!liteLLMBase.startsWith("http")) {
+            healthStatus.isConfigured = false;
+            healthStatus.configurationIssues.push("Invalid LITELLM_BASE_URL format");
+            healthStatus.recommendations.push("Set LITELLM_BASE_URL to a valid URL (e.g., http://localhost:4000)");
+            return;
+        }
+        const availability = await this.checkLiteLLMAvailability({
+            model: this.getConfiguredLiteLLMModel(),
+            timeout,
+        });
+        if (!availability.available) {
+            healthStatus.isConfigured = false;
+            healthStatus.configurationIssues.push(`LiteLLM runtime check failed: ${availability.reason ?? "unknown error"}`);
+            healthStatus.recommendations.push("Start the LiteLLM proxy and ensure the configured model is available from /v1/models");
+            return;
+        }
+        healthStatus.isConfigured = true;
+    }
     /**
      * Check Ollama configuration
      */
-    static async checkOllamaConfig(healthStatus) {
-        const ollamaBase = process.env.OLLAMA_API_BASE || "http://localhost:11434";
+    static async checkOllamaConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT) {
+        const ollamaBase = this.getOllamaBaseUrl();
         if (!ollamaBase.startsWith("http")) {
-            healthStatus.configurationIssues.push("Invalid OLLAMA_API_BASE format");
-            healthStatus.recommendations.push("Set OLLAMA_API_BASE to a valid URL (e.g., http://localhost:11434)");
+            healthStatus.isConfigured = false;
+            healthStatus.configurationIssues.push("Invalid OLLAMA_BASE_URL format (OLLAMA_API_BASE is still accepted as a legacy alias)");
+            healthStatus.recommendations.push("Set OLLAMA_BASE_URL to a valid URL (e.g., http://localhost:11434). OLLAMA_API_BASE remains supported as a legacy alias.");
+            return;
         }
+        const availability = await this.checkOllamaAvailability({
+            model: this.getConfiguredOllamaModel(),
+            timeout,
+        });
+        if (!availability.available) {
+            healthStatus.isConfigured = false;
+            healthStatus.configurationIssues.push(`Ollama runtime check failed: ${availability.reason ?? "unknown error"}`);
+            healthStatus.recommendations.push("Start Ollama and install the configured model before using Ollama as a fallback provider");
+            return;
+        }
+        healthStatus.isConfigured = true;
     }
     /**
      * Get common models for a provider
@@ -703,8 +892,21 @@ export class ProviderHealthChecker {
                 return [BedrockModels.CLAUDE_3_SONNET, BedrockModels.CLAUDE_3_HAIKU];
             case AIProviderName.AZURE:
                 return [OpenAIModels.GPT_4O, OpenAIModels.GPT_4O_MINI, "gpt-35-turbo"];
-            case AIProviderName.OLLAMA:
-                return ["llama3.2:latest", "llama3.1:latest", "mistral:latest"];
+            case AIProviderName.LITELLM:
+                return [
+                    "openai/gpt-4o-mini",
+                    "anthropic/claude-3-haiku",
+                    "google/gemini-2.5-flash",
+                ];
+            case AIProviderName.OLLAMA: {
+                const envModel = process.env.OLLAMA_MODEL;
+                const defaults = [
+                    "llama3.2:latest",
+                    "llama3.1:latest",
+                    "mistral:latest",
+                ];
+                return envModel ? [envModel, ...defaults] : defaults;
+            }
             default:
                 return [];
         }
@@ -1139,18 +1341,61 @@ export class ProviderHealthChecker {
             this.consecutiveFailures.clear();
         }
     }
+    static async checkFallbackProviderAvailability(providerName, model) {
+        const provider = providerName;
+        if (provider === AIProviderName.OLLAMA) {
+            const availability = await this.checkOllamaAvailability({
+                model,
+                timeout: 2000,
+            });
+            return {
+                available: availability.available,
+                reason: availability.reason,
+            };
+        }
+        if (provider === AIProviderName.LITELLM) {
+            const availability = await this.checkLiteLLMAvailability({
+                model,
+                timeout: 2000,
+            });
+            return {
+                available: availability.available,
+                reason: availability.reason,
+            };
+        }
+        try {
+            const health = await this.checkProviderHealth(provider, {
+                includeConnectivityTest: false,
+                cacheResults: true,
+                maxCacheAge: 15_000,
+                timeout: 2000,
+            });
+            return {
+                available: health.isHealthy,
+                reason: health.error || health.configurationIssues[0] || health.warning,
+            };
+        }
+        catch (error) {
+            return {
+                available: false,
+                reason: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
     /**
      * Get the best healthy provider from a list of options (NON-BLOCKING)
      * Prioritizes healthy providers over configured but unhealthy ones
      * Uses fast, cached health checks to avoid blocking initialization
      */
     static async getBestHealthyProvider(preferredProviders = [
+        "litellm",
+        "ollama",
         "openai",
         "anthropic",
         "vertex",
+        "google-ai",
         "bedrock",
         "azure",
-        "google-ai",
     ]) {
         const healthStatuses = await this.checkAllProvidersHealth({
             includeConnectivityTest: false, // Quick config check only
@@ -1191,6 +1436,7 @@ export class ProviderHealthChecker {
             AIProviderName.OPENAI,
             AIProviderName.BEDROCK,
             AIProviderName.AZURE,
+            AIProviderName.LITELLM,
             AIProviderName.OLLAMA,
         ];
         const healthChecks = providers.map((provider) => this.checkProviderHealth(provider, options));

package/dist/lib/utils/providerUtils.js

@@ -50,7 +50,8 @@ export async function getBestProvider(requestedProvider) {
         return process.env.DEFAULT_PROVIDER;
     }
     // Special case for Ollama - prioritize local when available
-    if (process.env.OLLAMA_BASE_URL && process.env.OLLAMA_MODEL) {
+    if ((process.env.OLLAMA_BASE_URL || process.env.OLLAMA_API_BASE) &&
+        process.env.OLLAMA_MODEL) {
         try {
             if (await isProviderAvailable("ollama")) {
                 logger.debug(`[getBestProvider] Prioritizing working local Ollama`);
@@ -63,15 +64,18 @@ export async function getBestProvider(requestedProvider) {
     }
     /**
      * Provider priority order rationale:
-     * - Vertex (Google Cloud AI) is prioritized first for its enterprise-grade reliability and advanced model capabilities.
-     * - Google AI follows as second priority for comprehensive Google AI ecosystem support.
+     * - LiteLLM and Ollama are prioritized first for local/self-hosted deployments,
+     *   avoiding unnecessary dependence on external providers during fallback scenarios.
+     * - Vertex (Google Cloud AI) follows for enterprise-grade reliability.
+     * - Google AI follows as second cloud priority for comprehensive Google AI ecosystem support.
      * - OpenAI maintains high priority due to its consistent reliability and broad model support.
-     * - Other providers are ordered based on a combination of reliability, feature set, and historical performance in our use cases.
-     * - Ollama is kept as a fallback for local deployments when available.
+     * - Other providers are ordered based on a combination of reliability, feature set, and historical performance.
      * Please update this comment if the order is changed in the future, and document the rationale for maintainability.
      */
     const providers = [
-        "vertex", // Prioritize Google Cloud AI (Vertex) first
+        "litellm", // Prioritize self-hosted proxy deployments first
+        "ollama", // Local models when the configured runtime target is installed
+        "vertex", // Google Cloud AI (enterprise)
         "google-ai", // Google AI ecosystem support
         "openai", // Reliable with broad model support
         "anthropic",
@@ -79,7 +83,6 @@ export async function getBestProvider(requestedProvider) {
         "azure",
         "mistral",
         "huggingface",
-        "ollama", // Keep as fallback
     ];
     for (const provider of providers) {
         if (await isProviderAvailable(provider)) {
@@ -99,22 +102,13 @@ async function isProviderAvailable(providerName) {
     if (!hasProviderEnvVars(providerName) && providerName !== "ollama") {
         return false;
     }
+    if (providerName === "litellm") {
+        const availability = await ProviderHealthChecker.checkFallbackProviderAvailability(AIProviderName.LITELLM, process.env.LITELLM_MODEL || "openai/gpt-4o-mini");
+        return availability.available;
+    }
     if (providerName === "ollama") {
-        try {
-            const response = await fetch("http://localhost:11434/api/tags", {
-                method: "GET",
-                signal: AbortSignal.timeout(2000),
-            });
-            if (response.ok) {
-                const { models } = await response.json();
-                const defaultOllamaModel = "llama3.2:latest";
-                return models.some((m) => m.name === defaultOllamaModel);
-            }
-            return false;
-        }
-        catch {
-            return false;
-        }
+        const availability = await ProviderHealthChecker.checkFallbackProviderAvailability(AIProviderName.OLLAMA, process.env.OLLAMA_MODEL || "llama3.1:8b");
+        return availability.available;
     }
     try {
         const provider = await AIProviderFactory.createProvider(providerName);
@@ -414,6 +408,7 @@ export function getAvailableProviders() {
         "anthropic",
         "azure",
         "google-ai",
+        "litellm",
         "huggingface",
         "ollama",
         "mistral",

package/dist/lib/utils/toolChoice.d.ts

@@ -0,0 +1,4 @@
+import type { Tool, ToolChoice } from "ai";
+export declare function resolveToolChoice(options: {
+    toolChoice?: ToolChoice<Record<string, Tool>>;
+}, tools: Record<string, Tool> | undefined, shouldUseTools: boolean): ToolChoice<Record<string, Tool>> | "none";

package/dist/lib/utils/toolChoice.js

@@ -0,0 +1,7 @@
+export function resolveToolChoice(options, tools, shouldUseTools) {
+    if (!shouldUseTools || !tools || Object.keys(tools).length === 0) {
+        return "none";
+    }
+    return options.toolChoice ?? "auto";
+}
+//# sourceMappingURL=toolChoice.js.map

package/dist/mcp/toolRegistry.d.ts

@@ -69,6 +69,8 @@ export declare class MCPToolRegistry extends MCPRegistry {
         permissions?: string[];
         context?: ExecutionContext;
     }): Promise<ToolInfo[]>;
+    private resolveToolExecutionTarget;
+    private createExecutionContext;
     /**
      * Get tool information with server details
      */

package/dist/mcp/toolRegistry.js

@@ -9,6 +9,7 @@ import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { directAgentTools } from "../agent/directTools.js";
 import { detectCategory, createMCPServerInfo } from "../utils/mcpDefaults.js";
 import { FlexibleToolValidator } from "./flexibleToolValidator.js";
+import { ErrorFactory } from "../utils/errorHandling.js";
 import { HITLUserRejectedError, HITLTimeoutError } from "../hitl/hitlErrors.js";
 import { withSpan, tracers, ATTR } from "../telemetry/index.js";
 import { getAuthContext } from "../auth/authContext.js";
@@ -263,22 +264,7 @@ export class MCPToolRegistry extends MCPRegistry {
                     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;
-                    }
-                }
+                const { tool, toolId } = this.resolveToolExecutionTarget(toolName);
                 if (!tool) {
                     throw new Error(`Tool '${toolName}' not found in registry`);
                 }
@@ -291,21 +277,7 @@ export class MCPToolRegistry extends MCPRegistry {
                         : "mcp";
                 span.setAttribute("tool.type", toolType);
                 span.setAttribute(ATTR.MCP_SERVER_ID, serverId);
-                // Try to get auth context if available
-                let authUserId;
-                try {
-                    const authCtx = getAuthContext();
-                    authUserId = authCtx?.user?.id;
-                }
-                catch {
-                    // Auth context not available — that's fine
-                }
-                // Create execution context if not provided
-                const execContext = {
-                    ...context,
-                    sessionId: context?.sessionId ?? randomUUID(),
-                    userId: context?.userId ?? authUserId,
-                };
+                const execContext = this.createExecutionContext(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}`);
@@ -504,6 +476,35 @@ export class MCPToolRegistry extends MCPRegistry {
         registryLogger.debug(`Listed ${result.length} unique tools (${filter ? "filtered" : "unfiltered"})`);
         return result;
     }
+    resolveToolExecutionTarget(toolName) {
+        let tool = this.tools.get(toolName);
+        registryLogger.info(`🔍 [TOOL_LOOKUP] Direct lookup result for '${toolName}':`, !!tool);
+        let toolId = toolName;
+        if (!tool) {
+            const matches = Array.from(this.tools.entries()).filter(([, toolInfo]) => toolInfo.name === toolName);
+            if (matches.length > 1) {
+                throw ErrorFactory.toolExecutionFailed(toolName, new Error(`Ambiguous tool name '${toolName}'. Use fully-qualified name 'serverId.${toolName}'.`));
+            }
+            if (matches.length === 1) {
+                [toolId, tool] = matches[0];
+            }
+        }
+        return { tool, toolId };
+    }
+    createExecutionContext(context) {
+        let authUserId;
+        try {
+            authUserId = getAuthContext()?.user?.id;
+        }
+        catch {
+            // Auth context not available — that's fine
+        }
+        return {
+            ...context,
+            sessionId: context?.sessionId ?? randomUUID(),
+            userId: context?.userId ?? authUserId,
+        };
+    }
     /**
      * Get tool information with server details
      */