@juspay/neurolink 9.42.0 → 9.42.1

package/dist/lib/tasks/taskManager.js

@@ -158,7 +158,28 @@ export class TaskManager {
             await backend.schedule(task, (t) => this.onTaskTick(t));
         }
         catch (err) {
-            await store.delete(task.id);
+            this.callbacks.delete(task.id);
+            try {
+                await store.delete(task.id);
+            }
+            catch (cleanupError) {
+                // Deletion failed — task remains persisted as active. Attempt to mark it
+                // failed so it reaches a terminal state and operators can identify it.
+                logger.error("[TaskManager] Failed to clean up task after schedule error — task may remain persisted as active", {
+                    taskId: task.id,
+                    scheduleError: String(err),
+                    cleanupError: String(cleanupError),
+                });
+                try {
+                    await store.update(task.id, { status: "failed" });
+                }
+                catch (terminalError) {
+                    logger.error("[TaskManager] Failed to force task to terminal state — manual cleanup required", {
+                        taskId: task.id,
+                        error: String(terminalError),
+                    });
+                }
+            }
             throw err;
         }
         this.emit("task:created", task);
@@ -209,6 +230,7 @@ export class TaskManager {
                 taskUpdates[field] = updates[field];
             }
         }
+        const shouldClearHistory = updates.mode !== undefined && updates.mode !== "continuation";
         // Special-case: mode changes require sessionId handling
         if (updates.mode !== undefined) {
             if (updates.mode === "continuation" && !existing.sessionId) {
@@ -216,14 +238,39 @@ export class TaskManager {
             }
             else if (updates.mode !== "continuation") {
                 taskUpdates.sessionId = undefined;
-                await store.clearHistory(taskId);
             }
         }
         const updated = await store.update(taskId, taskUpdates);
         // Re-schedule if schedule changed and task is active
         if (updates.schedule && updated.status === "active") {
+            const attemptedSchedule = updated.schedule;
             await backend.cancel(taskId);
-            await backend.schedule(updated, (t) => this.onTaskTick(t));
+            try {
+                await backend.schedule(updated, (t) => this.onTaskTick(t));
+            }
+            catch (error) {
+                await this.restoreScheduledTask(existing, "update schedule rollback");
+                await this.rollbackTaskUpdate(taskId, existing, error);
+                throw TaskError.create("SCHEDULE_FAILED", `Failed to update schedule for task ${taskId}`, {
+                    cause: error instanceof Error ? error : undefined,
+                    details: {
+                        taskId,
+                        previousSchedule: existing.schedule,
+                        attemptedSchedule,
+                    },
+                });
+            }
+        }
+        if (shouldClearHistory) {
+            try {
+                await store.clearHistory(taskId);
+            }
+            catch (error) {
+                logger.warn("[TaskManager] Failed to clear task history after mode update", {
+                    taskId,
+                    error: String(error),
+                });
+            }
         }
         return updated;
     }
@@ -248,7 +295,14 @@ export class TaskManager {
             throw TaskError.create("INVALID_TASK_STATUS", `Cannot pause task with status: ${task.status}`);
         }
         await backend.pause(taskId);
-        const updated = await store.update(taskId, { status: "paused" });
+        let updated;
+        try {
+            updated = await store.update(taskId, { status: "paused" });
+        }
+        catch (error) {
+            await this.restoreScheduledTask(task, "pause rollback");
+            throw error;
+        }
         this.emit("task:paused", updated);
         return updated;
     }
@@ -264,7 +318,16 @@ export class TaskManager {
             throw TaskError.create("INVALID_TASK_STATUS", `Cannot resume task with status: ${task.status}`);
         }
         const updated = await store.update(taskId, { status: "active" });
-        await backend.schedule(updated, (t) => this.onTaskTick(t));
+        try {
+            await backend.schedule(updated, (t) => this.onTaskTick(t));
+        }
+        catch (error) {
+            await this.rollbackTaskUpdate(taskId, task, error);
+            throw TaskError.create("SCHEDULE_FAILED", `Failed to resume task ${taskId}`, {
+                cause: error instanceof Error ? error : undefined,
+                details: { taskId, schedule: task.schedule },
+            });
+        }
         this.emit("task:resumed", updated);
         return updated;
     }
@@ -301,6 +364,38 @@ export class TaskManager {
         return this.backend.isHealthy();
     }
     // ── Internal ──────────────────────────────────────────
+    async restoreScheduledTask(task, reason) {
+        if (task.status !== "active") {
+            return;
+        }
+        try {
+            await this.getBackend().schedule(task, (t) => this.onTaskTick(t));
+            logger.warn("[TaskManager] Restored task schedule after rollback", {
+                taskId: task.id,
+                reason,
+            });
+        }
+        catch (restoreError) {
+            logger.error("[TaskManager] Failed to restore task schedule during rollback", {
+                taskId: task.id,
+                reason,
+                error: String(restoreError),
+            });
+        }
+    }
+    async rollbackTaskUpdate(taskId, previousTask, error) {
+        try {
+            return await this.getStore().update(taskId, previousTask);
+        }
+        catch (rollbackError) {
+            logger.error("[TaskManager] Failed to roll back task update — store and in-memory state may be diverged; manual reconciliation required", {
+                taskId,
+                originalError: String(error),
+                rollbackError: String(rollbackError),
+            });
+            throw rollbackError;
+        }
+    }
     /**
      * Called by the backend on each scheduled tick.
      * Executes the task, updates state, fires callbacks/events.

package/dist/lib/telemetry/telemetryService.js

@@ -54,13 +54,17 @@ export class TelemetryService {
             if (!provider) {
                 return false;
             }
-            const delegateName = provider._delegate?.constructor?.name || "";
-            if (delegateName && delegateName !== "NoopTracerProvider") {
+            const providerName = provider.constructor?.name || "";
+            if (providerName &&
+                providerName !== "ProxyTracerProvider" &&
+                providerName !== "NoopTracerProvider") {
                 return true;
             }
-            const providerName = provider.constructor?.name || "";
-            return (providerName !== "ProxyTracerProvider" &&
-                providerName !== "NoopTracerProvider");
+            const delegate = typeof provider.getDelegate === "function"
+                ? provider.getDelegate()
+                : provider._delegate;
+            const delegateName = delegate?.constructor?.name || "";
+            return Boolean(delegateName && delegateName !== "NoopTracerProvider");
         }
         catch (error) {
             logger.warn("[Telemetry] Failed checking for external TracerProvider", {

package/dist/lib/types/proxyTypes.d.ts

@@ -13,6 +13,8 @@
  * - src/lib/proxy/accountQuota.ts (quota type)
  * - src/lib/server/routes/claudeProxyRoutes.ts (runtime state, deps)
  */
+import type { Span } from "@opentelemetry/api";
+import type { ProxyTracer } from "../proxy/proxyTracer.js";
 /**
  * Type describing the ModelRouter contract.
  * Defined here to avoid a circular dependency between types and implementation.
@@ -242,7 +244,7 @@ export type ParsedClaudeRequest = {
     /** Tools translated to AI SDK-compatible shape for provider fallback. */
     tools: Record<string, {
         description?: string;
-        inputSchema?: unknown;
+        inputSchema: unknown;
         execute?: (...args: unknown[]) => unknown;
     }>;
     /**
@@ -361,6 +363,14 @@ export type TlsFingerprintOptions = {
     /** Whether the stub should log a warning that it is a no-op. */
     warnOnUse?: boolean;
 };
+/**
+ * Proxy operating mode:
+ * - "full"        — managed accounts, retry, rotation, polyfill (default)
+ * - "passthrough" — no polyfill/retry/rotation, but body is still parsed and re-serialized
+ * - "transparent" — zero-mutation byte relay: raw body forwarded as-is, minimal header filtering,
+ *                   SSE interceptor for cache metrics only (bytes pass through unmodified)
+ */
+export type ProxyMode = "full" | "passthrough" | "transparent";
 export type RouteResult = {
     provider: string | null;
     model: string;
@@ -453,6 +463,119 @@ export type RequestAttemptLogEntry = {
     /** OTel span ID for correlation with distributed traces */
     spanId?: string;
 };
+export type ProxyBodyCaptureInput = {
+    phase: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    bodySize?: number;
+    contentType?: string;
+    responseStatus?: number;
+    durationMs?: number;
+    account?: string;
+    accountType?: string;
+    attempt?: number;
+    metadata?: Record<string, unknown>;
+};
+export type ProxyBodyCaptureLogger = (capture: ProxyBodyCaptureInput) => void;
+export type ClaudeFinalRequestLogger = (status: number, accountLabel: string, accountType: string, errorType?: string, errorMessage?: string, extra?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+}) => void;
+export type ClaudeLoggedErrorBuilder = (status: number, message: string, errorType?: string, extra?: {
+    account?: string;
+    accountType?: string;
+    attempt?: number;
+}) => ClaudeErrorResponse;
+export type ClaudeRequestRuntimeContext = {
+    tracer?: ProxyTracer;
+    requestStartTime: number;
+    logProxyBody: ProxyBodyCaptureLogger;
+    logFinalRequest: ClaudeFinalRequestLogger;
+    buildLoggedClaudeError: ClaudeLoggedErrorBuilder;
+};
+export type AnthropicAttemptLogger = (status: number, errorType?: string, errorMessage?: string, extra?: {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheCreationTokens?: number;
+    cacheReadTokens?: number;
+}) => void;
+export type AnthropicLoopState = {
+    lastError: unknown;
+    sawRateLimit: boolean;
+    sawNetworkError: boolean;
+    sawTransientFailure: boolean;
+    invalidRequestFailure: {
+        status: number;
+        body: string;
+        contentType?: string;
+    } | null;
+    authFailureMessage: string | null;
+    attemptNumber: number;
+};
+export type AnthropicUpstreamBody = {
+    bodyStr: string;
+    sessionId?: string;
+};
+export type AnthropicUpstreamBodyBuilder = (token: string) => AnthropicUpstreamBody;
+export type LoadedClaudeAccountContext = {
+    accounts: ProxyPassthroughAccount[];
+    enabledAccounts: ProxyPassthroughAccount[];
+    orderedAccounts: ProxyPassthroughAccount[];
+    bodyStr: string;
+    requestStart: number;
+    toolCount: number;
+    url: string;
+    clientHeaders: Record<string, string | undefined>;
+    isClaudeClientRequest: boolean;
+};
+export type AnthropicSuccessResult = {
+    retryNextAccount: true;
+} | {
+    response: Response | unknown;
+};
+export type AnthropicAuthRetryResult = {
+    response?: Response | unknown;
+    continueLoop: boolean;
+    lastError: unknown;
+    authFailureMessage: string | null;
+    sawRateLimit: boolean;
+    sawTransientFailure: boolean;
+    sawNetworkError: boolean;
+    upstreamSpan?: Span;
+};
+export type AnthropicNonOkResult = {
+    response?: Response | unknown;
+    continueLoop: boolean;
+    lastError: unknown;
+    authFailureMessage: string | null;
+    sawTransientFailure: boolean;
+    invalidRequestFailure: {
+        status: number;
+        body: string;
+        contentType?: string;
+    } | null;
+    upstreamSpan?: Span;
+};
+export type PreparedAnthropicAccountAttempt = {
+    continueLoop: boolean;
+    lastError: unknown;
+    authFailureMessage: string | null;
+    headers?: Record<string, string>;
+    buildUpstreamBody?: AnthropicUpstreamBodyBuilder;
+    finalBodyStr?: string;
+    fetchStartMs?: number;
+    upstreamSpan?: Span;
+};
+export type AnthropicUpstreamFetchResult = {
+    continueLoop: boolean;
+    response?: Response;
+    lastError: unknown;
+    sawRateLimit: boolean;
+    sawNetworkError: boolean;
+    upstreamSpan?: Span;
+};
 export type AccountStats = {
     label: string;
     type: string;

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

@@ -30,6 +30,7 @@ export declare class ProviderHealthChecker {
      * Check connectivity to provider endpoints
      */
     private static checkConnectivity;
+    private static getConnectivityHeaders;
     /**
      * Check model availability (if possible without making API calls)
      */

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)
@@ -261,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) {
@@ -320,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)
      */
@@ -455,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);
@@ -467,10 +479,10 @@ export class ProviderHealthChecker {
                 await this.checkAzureConfig(healthStatus);
                 break;
             case AIProviderName.LITELLM:
-                await this.checkLiteLLMConfig(healthStatus);
+                await this.checkLiteLLMConfig(healthStatus, timeout);
                 break;
             case AIProviderName.OLLAMA:
-                await this.checkOllamaConfig(healthStatus);
+                await this.checkOllamaConfig(healthStatus, timeout);
                 break;
         }
     }
@@ -722,9 +734,12 @@ export class ProviderHealthChecker {
             .filter((model) => typeof model === "string");
     }
     static hasRequestedModel(availableModels, requestedModel) {
-        return availableModels.some((model) => model === requestedModel ||
-            model.startsWith(`${requestedModel}:`) ||
-            requestedModel.startsWith(`${model}:`));
+        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(), {
@@ -789,7 +804,7 @@ export class ProviderHealthChecker {
             };
         }
     }
-    static async checkLiteLLMConfig(healthStatus) {
+    static async checkLiteLLMConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT) {
         const liteLLMBase = this.getLiteLLMBaseUrl();
         if (!liteLLMBase.startsWith("http")) {
             healthStatus.isConfigured = false;
@@ -799,7 +814,7 @@ export class ProviderHealthChecker {
         }
         const availability = await this.checkLiteLLMAvailability({
             model: this.getConfiguredLiteLLMModel(),
-            timeout: 2000,
+            timeout,
         });
         if (!availability.available) {
             healthStatus.isConfigured = false;
@@ -812,7 +827,7 @@ export class ProviderHealthChecker {
     /**
      * Check Ollama configuration
      */
-    static async checkOllamaConfig(healthStatus) {
+    static async checkOllamaConfig(healthStatus, timeout = this.DEFAULT_TIMEOUT) {
         const ollamaBase = this.getOllamaBaseUrl();
         if (!ollamaBase.startsWith("http")) {
             healthStatus.isConfigured = false;
@@ -822,7 +837,7 @@ export class ProviderHealthChecker {
         }
         const availability = await this.checkOllamaAvailability({
             model: this.getConfiguredOllamaModel(),
-            timeout: 2000,
+            timeout,
         });
         if (!availability.available) {
             healthStatus.isConfigured = false;

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`);
@@ -64,7 +65,7 @@ export async function getBestProvider(requestedProvider) {
     /**
      * Provider priority order rationale:
      * - LiteLLM and Ollama are prioritized first for local/self-hosted deployments,
-     *   avoiding cloud quota/rate-limit issues during fallback scenarios.
+     *   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.
@@ -72,8 +73,8 @@ export async function getBestProvider(requestedProvider) {
      * Please update this comment if the order is changed in the future, and document the rationale for maintainability.
      */
     const providers = [
-        "litellm", // Prioritize self-hosted/proxy (no rate limits)
-        "ollama", // Local models (no rate limits)
+        "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
@@ -101,25 +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 = process.env.OLLAMA_MODEL || "llama3.1:8b";
-                // Check for exact match first, then prefix match (e.g. "gemma3:27b" matches "gemma3:27b-fp16")
-                return models.some((m) => m.name === defaultOllamaModel ||
-                    (typeof m.name === "string" &&
-                        m.name.startsWith(defaultOllamaModel.split(":")[0] + ":")));
-            }
-            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);

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
      */