@juspay/neurolink 12.9.5 → 12.9.6

package/dist/neurolink.d.ts

@@ -1943,9 +1943,37 @@ export declare class NeuroLink {
      * @param options - Execution options
      * @returns Tool execution result
      */
-    executeExternalMCPTool(serverId: string, toolName: string, parameters: JsonObject, options?: {
+    executeExternalMCPTool(serverId: string, requestedToolName: string, parameters: JsonObject, options?: {
         timeout?: number;
     }): Promise<unknown>;
+    /**
+     * Resolve a tool name for a direct external MCP execution
+     * (`executeExternalMCPTool`) against the server's currently discovered
+     * tools.
+     *
+     * `experimental_repairToolCall` only runs inside the AI-SDK's own
+     * streamText/generateText loop (see toolCallRepair.ts), so a near-miss
+     * tool name reaching `executeExternalMCPTool` directly previously had no
+     * recovery at all — just the generic `Tool 'x' not found for server 'y'`
+     * `Error` that `ToolDiscoveryService.executeTool` throws deeper in the
+     * stack. This reuses the same name-matching policy
+     * (`resolveToolName`: case-insensitive exact → unambiguous substring →
+     * Levenshtein) so a repair here is accepted under exactly the rules
+     * already proven for the generation path.
+     *
+     * Exact match is a zero-risk fast path: it is returned unchanged before
+     * any resolution attempt, so every existing caller that already sends a
+     * valid name — including the AI-SDK path's `createExternalMCPTool`, which
+     * always executes with a name it just discovered — sees no behaviour
+     * change.
+     *
+     * Deliberately does NOT attempt a repair when the server is unknown or
+     * not connected: `ExternalServerManager.executeTool` throws distinct,
+     * more accurate errors for those states ("Server 'x' not found" /
+     * "not in connected state"), and resolving against an empty tool list
+     * here would replace those with a misleading "tool not found" instead.
+     */
+    private resolveDirectMcpToolName;
     /**
      * Get all tools from external MCP servers
      * @returns Array of external tool information

package/dist/neurolink.js

@@ -89,6 +89,7 @@ import { logger, mcpLogger } from "./utils/logger.js";
 import { redactUrlCredentials, safeDebugSerialize, sanitizeRecord, stringifyContentSafe, } from "./utils/logSanitize.js";
 import { extractMcpErrorText } from "./utils/mcpErrorText.js";
 import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults.js";
+import { ExternalMcpToolNotFoundError, rankToolNameCandidates, resolveToolName, } from "./utils/toolCallRepair.js";
 import { resolveModel } from "./utils/modelAliasResolver.js";
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
@@ -11732,8 +11733,16 @@ Current user's request: ${currentInput}`;
      * @param options - Execution options
      * @returns Tool execution result
      */
-    async executeExternalMCPTool(serverId, toolName, parameters, options) {
+    async executeExternalMCPTool(serverId, requestedToolName, parameters, options) {
+        // Falls back to the requested name so the catch block below still has
+        // something meaningful to log if resolution itself is what throws.
+        let toolName = requestedToolName;
         try {
+            // Direct-boundary name repair (see resolveDirectMcpToolName): an exact
+            // match returns requestedToolName unchanged, so every existing caller
+            // — including the AI-SDK generation path's createExternalMCPTool,
+            // which always calls with an already-discovered name — is unaffected.
+            toolName = this.resolveDirectMcpToolName(serverId, requestedToolName);
             mcpLogger.debug(`[NeuroLink] Executing external MCP tool: ${toolName} on ${serverId}`);
             // BZ-664: Check existing ToolResultCache before executing to avoid
             // duplicate identical calls within the same session.
@@ -11803,6 +11812,65 @@ Current user's request: ${currentInput}`;
             throw error;
         }
     }
+    /**
+     * Resolve a tool name for a direct external MCP execution
+     * (`executeExternalMCPTool`) against the server's currently discovered
+     * tools.
+     *
+     * `experimental_repairToolCall` only runs inside the AI-SDK's own
+     * streamText/generateText loop (see toolCallRepair.ts), so a near-miss
+     * tool name reaching `executeExternalMCPTool` directly previously had no
+     * recovery at all — just the generic `Tool 'x' not found for server 'y'`
+     * `Error` that `ToolDiscoveryService.executeTool` throws deeper in the
+     * stack. This reuses the same name-matching policy
+     * (`resolveToolName`: case-insensitive exact → unambiguous substring →
+     * Levenshtein) so a repair here is accepted under exactly the rules
+     * already proven for the generation path.
+     *
+     * Exact match is a zero-risk fast path: it is returned unchanged before
+     * any resolution attempt, so every existing caller that already sends a
+     * valid name — including the AI-SDK path's `createExternalMCPTool`, which
+     * always executes with a name it just discovered — sees no behaviour
+     * change.
+     *
+     * Deliberately does NOT attempt a repair when the server is unknown or
+     * not connected: `ExternalServerManager.executeTool` throws distinct,
+     * more accurate errors for those states ("Server 'x' not found" /
+     * "not in connected state"), and resolving against an empty tool list
+     * here would replace those with a misleading "tool not found" instead.
+     */
+    resolveDirectMcpToolName(serverId, requestedName) {
+        const server = this.getExternalMCPServer(serverId);
+        if (!server || server.status !== "connected" || !server.client) {
+            return requestedName;
+        }
+        const availableNames = this.getExternalMCPServerTools(serverId).map((tool) => tool.name);
+        if (availableNames.includes(requestedName)) {
+            return requestedName;
+        }
+        const resolution = resolveToolName(requestedName, availableNames);
+        if (!resolution) {
+            throw new ExternalMcpToolNotFoundError(requestedName, serverId, rankToolNameCandidates(requestedName, availableNames));
+        }
+        // Recorded on a short-lived span rather than the method's return value:
+        // executeExternalMCPTool returns the raw upstream tool result verbatim
+        // (widely consumed as-is, e.g. by createExternalMCPTool's execute()),
+        // so wrapping it to carry resolution metadata would be a breaking
+        // change for every existing direct caller.
+        tracers.mcp.startActiveSpan("neurolink.mcp.toolNameRepair", {
+            attributes: {
+                "mcp.server_id": serverId,
+                "mcp.tool_name.requested": requestedName,
+                "mcp.tool_name.resolved": resolution.name,
+                "mcp.tool_name.repair_strategy": resolution.strategy,
+                ...(resolution.score !== undefined
+                    ? { "mcp.tool_name.repair_score": resolution.score }
+                    : {}),
+            },
+        }, (span) => span.end());
+        mcpLogger.info(`[NeuroLink] Repaired external MCP tool name at direct execution boundary: "${requestedName}" → "${resolution.name}" (${resolution.strategy}) on server '${serverId}'`);
+        return resolution.name;
+    }
     /**
      * Get all tools from external MCP servers
      * @returns Array of external tool information

package/dist/types/mcp.d.ts

@@ -422,6 +422,22 @@ export type ToolDiscoveryResult = {
     /** Server ID */
     serverId: string;
 };
+/**
+ * Outcome of matching a possibly-misspelled tool name against a list of
+ * available tool names (see `resolveToolName` in
+ * src/lib/utils/toolCallRepair.ts). Shared between the AI-SDK generation-path
+ * repair (`experimental_repairToolCall`) and direct MCP execution boundaries
+ * (`NeuroLink.executeExternalMCPTool`) so both recover from the same class of
+ * near-miss the same way.
+ */
+export type ToolNameResolution = {
+    /** The resolved, available tool name. */
+    name: string;
+    /** Which strategy produced the match, in the order they are attempted. */
+    strategy: "case" | "substring" | "levenshtein";
+    /** Normalized Levenshtein distance (0–1) — only set when strategy is "levenshtein". */
+    score?: number;
+};
 /**
  * External MCP tool execution options
  * Moved from src/lib/mcp/toolDiscoveryService.ts

package/dist/utils/toolCallRepair.d.ts

@@ -1,9 +1,51 @@
 import type { ToolCallRepairFunction, ToolSet } from "../types/index.js";
+import type { ToolNameResolution } from "../types/index.js";
 /**
  * Create an `experimental_repairToolCall` handler for streamText/generateText.
  * Fully dynamic — reads the tool schema at repair time, no configuration needed.
  */
 export declare function createToolCallRepair(): ToolCallRepairFunction<ToolSet>;
+/**
+ * Match a possibly-misspelled tool name against a list of available tool
+ * names. Strategies (in order): case-insensitive exact → unambiguous
+ * substring → Levenshtein.
+ *
+ * Pulled out of `repairToolName` so the same matching policy can be reused
+ * outside the AI-SDK generation loop — `experimental_repairToolCall` only
+ * runs inside `streamText`/`generateText`, so a name typo at a direct MCP
+ * execution boundary (`NeuroLink.executeExternalMCPTool`) previously had no
+ * recovery at all. This function is pure name-matching: no `LanguageModelV3ToolCall`,
+ * no logging, so callers with a different call shape can reuse it directly.
+ */
+export declare function resolveToolName(calledName: string, availableTools: string[]): ToolNameResolution | null;
+/**
+ * Rank every available tool name by similarity to `calledName` (ascending
+ * normalized Levenshtein distance) and return the closest `limit`.
+ *
+ * Used to build the candidate list on `ExternalMcpToolNotFoundError` when
+ * `resolveToolName` found no unambiguous match — unlike `resolveToolName`,
+ * this makes no accept/reject judgment, it just orders what is available so
+ * a caller (human or AI) can pick the right name themselves.
+ */
+export declare function rankToolNameCandidates(calledName: string, availableTools: string[], limit?: number): string[];
+/**
+ * Thrown at a direct MCP execution boundary (`NeuroLink.executeExternalMCPTool`)
+ * when `resolveToolName` cannot find an unambiguous match for a requested
+ * tool name against a server's discovered tools. Distinct from the plain
+ * `Error` that `ToolDiscoveryService.executeTool` throws deeper in the stack
+ * for the same condition, so callers can distinguish "no match — here are
+ * the closest names" from every other execution failure programmatically,
+ * instead of parsing a message string.
+ */
+export declare class ExternalMcpToolNotFoundError extends Error {
+    /** The tool name that was requested and could not be resolved. */
+    readonly requestedName: string;
+    /** The server the tool was requested against. */
+    readonly serverId: string;
+    /** Closest available tool names on that server, capped (see `rankToolNameCandidates`). */
+    readonly candidates: string[];
+    constructor(requestedName: string, serverId: string, candidates: string[]);
+}
 /**
  * Coerce a value to match the expected schema type.
  * Handles: string→number, JSON string→object, JSON string→array, value→[value].

package/dist/utils/toolCallRepair.js

@@ -25,31 +25,36 @@ export function createToolCallRepair() {
 }
 // ─── Tool Name Repair ──────────────────────────────────────────────
 /**
- * Attempt to match a wrong tool name against available tool names.
- * Strategies (in order): case-insensitive exact → substring → Levenshtein.
+ * Match a possibly-misspelled tool name against a list of available tool
+ * names. Strategies (in order): case-insensitive exact → unambiguous
+ * substring → Levenshtein.
+ *
+ * Pulled out of `repairToolName` so the same matching policy can be reused
+ * outside the AI-SDK generation loop — `experimental_repairToolCall` only
+ * runs inside `streamText`/`generateText`, so a name typo at a direct MCP
+ * execution boundary (`NeuroLink.executeExternalMCPTool`) previously had no
+ * recovery at all. This function is pure name-matching: no `LanguageModelV3ToolCall`,
+ * no logging, so callers with a different call shape can reuse it directly.
  */
-function repairToolName(toolCall, availableTools) {
-    const called = toolCall.toolName;
+export function resolveToolName(calledName, availableTools) {
     // Guard: empty or whitespace-only tool name cannot be meaningfully repaired
-    if (!called || called.trim().length === 0) {
+    if (!calledName || calledName.trim().length === 0) {
         return null;
     }
     // 1. Case-insensitive exact match
-    const ciMatch = availableTools.find((t) => t.toLowerCase() === called.toLowerCase());
+    const ciMatch = availableTools.find((t) => t.toLowerCase() === calledName.toLowerCase());
     if (ciMatch) {
-        logger.debug(`[ToolCallRepair] Name repair (case): "${called}" → "${ciMatch}"`);
-        return { ...toolCall, toolName: ciMatch };
+        return { name: ciMatch, strategy: "case" };
     }
     // 2. Substring match: "search_file" is substring of "search_files" or vice versa.
     // Only accept when exactly one tool matches to avoid ambiguous repairs.
-    const calledLower = called.toLowerCase();
+    const calledLower = calledName.toLowerCase();
     const subCandidates = availableTools.filter((t) => {
         const tLower = t.toLowerCase();
         return tLower.includes(calledLower) || calledLower.includes(tLower);
     });
     if (subCandidates.length === 1) {
-        logger.debug(`[ToolCallRepair] Name repair (substring): "${called}" → "${subCandidates[0]}"`);
-        return { ...toolCall, toolName: subCandidates[0] };
+        return { name: subCandidates[0], strategy: "substring" };
     }
     // 3. Levenshtein distance — accept if normalized distance < 0.3
     // Compare by normalized score (not raw edits) so length differences don't skew selection.
@@ -57,7 +62,7 @@ function repairToolName(toolCall, availableTools) {
     let bestNormalized = Infinity;
     for (const t of availableTools) {
         const dist = levenshtein(calledLower, t.toLowerCase());
-        const maxLen = Math.max(called.length, t.length);
+        const maxLen = Math.max(calledName.length, t.length);
         const normalized = maxLen === 0 ? 0 : dist / maxLen;
         if (normalized < 0.3 && normalized < bestNormalized) {
             bestNormalized = normalized;
@@ -65,12 +70,70 @@ function repairToolName(toolCall, availableTools) {
         }
     }
     if (bestMatch) {
-        logger.debug(`[ToolCallRepair] Name repair (levenshtein ${bestNormalized.toFixed(2)}): "${called}" → "${bestMatch}"`);
-        return { ...toolCall, toolName: bestMatch };
+        return { name: bestMatch, strategy: "levenshtein", score: bestNormalized };
     }
-    logger.debug(`[ToolCallRepair] Could not repair tool name "${called}". Available: [${availableTools.join(", ")}]`);
     return null;
 }
+/**
+ * Rank every available tool name by similarity to `calledName` (ascending
+ * normalized Levenshtein distance) and return the closest `limit`.
+ *
+ * Used to build the candidate list on `ExternalMcpToolNotFoundError` when
+ * `resolveToolName` found no unambiguous match — unlike `resolveToolName`,
+ * this makes no accept/reject judgment, it just orders what is available so
+ * a caller (human or AI) can pick the right name themselves.
+ */
+export function rankToolNameCandidates(calledName, availableTools, limit = 5) {
+    const calledLower = calledName.toLowerCase();
+    return [...availableTools]
+        .sort((a, b) => levenshtein(calledLower, a.toLowerCase()) -
+        levenshtein(calledLower, b.toLowerCase()))
+        .slice(0, limit);
+}
+/**
+ * Thrown at a direct MCP execution boundary (`NeuroLink.executeExternalMCPTool`)
+ * when `resolveToolName` cannot find an unambiguous match for a requested
+ * tool name against a server's discovered tools. Distinct from the plain
+ * `Error` that `ToolDiscoveryService.executeTool` throws deeper in the stack
+ * for the same condition, so callers can distinguish "no match — here are
+ * the closest names" from every other execution failure programmatically,
+ * instead of parsing a message string.
+ */
+export class ExternalMcpToolNotFoundError extends Error {
+    /** The tool name that was requested and could not be resolved. */
+    requestedName;
+    /** The server the tool was requested against. */
+    serverId;
+    /** Closest available tool names on that server, capped (see `rankToolNameCandidates`). */
+    candidates;
+    constructor(requestedName, serverId, candidates) {
+        const candidateList = candidates.length > 0 ? candidates.join(", ") : "(none registered)";
+        super(`Tool '${requestedName}' not found for server '${serverId}'. Closest available: ${candidateList}`);
+        this.name = "ExternalMcpToolNotFoundError";
+        this.requestedName = requestedName;
+        this.serverId = serverId;
+        this.candidates = candidates;
+    }
+}
+/**
+ * Attempt to match a wrong tool name against available tool names and
+ * produce a repaired `LanguageModelV3ToolCall` for the AI-SDK generation
+ * path. Thin wrapper around `resolveToolName` that restores this function's
+ * original debug-log wording so generation-path behaviour is unchanged.
+ */
+function repairToolName(toolCall, availableTools) {
+    const called = toolCall.toolName;
+    const resolution = resolveToolName(called, availableTools);
+    if (!resolution) {
+        logger.debug(`[ToolCallRepair] Could not repair tool name "${called}". Available: [${availableTools.join(", ")}]`);
+        return null;
+    }
+    const label = resolution.strategy === "levenshtein"
+        ? `levenshtein ${resolution.score.toFixed(2)}`
+        : resolution.strategy;
+    logger.debug(`[ToolCallRepair] Name repair (${label}): "${called}" → "${resolution.name}"`);
+    return { ...toolCall, toolName: resolution.name };
+}
 // ─── Tool Input Repair ─────────────────────────────────────────────
 /**
  * Attempt to repair wrong parameter names and types using the JSON schema.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "12.9.5",
+  "version": "12.9.6",
   "packageManager": "pnpm@10.15.1",
   "description": "TypeScript AI SDK with 24+ LLM providers behind one consistent API. MCP-native (connect any MCP server), voice TTS/STT/realtime, RAG, agents, memory, context compaction. OpenAI · Anthropic · Gemini · Bedrock · Azure · Ollama · DeepSeek · NVIDIA NIM and more.",
   "author": {
@@ -86,6 +86,7 @@
     "test:mcp:sdk": "pnpm exec tsx test/continuous-test-suite-mcp-sdk.ts",
     "test:mcp:cli": "pnpm exec tsx test/continuous-test-suite-mcp-cli.ts",
     "test:mcp:stdio-lifecycle": "pnpm exec tsx test/continuous-test-suite-mcp-stdio-lifecycle.ts",
+    "test:mcp-direct-name-repair": "pnpm exec tsx test/continuous-test-suite-mcp-direct-name-repair.ts",
     "test:mcp:full": "pnpm run test:mcp:infra && pnpm run test:mcp:spans && pnpm run test:mcp:stdio-lifecycle && pnpm run test:mcp:sdk && pnpm run test:mcp:cli && pnpm run test:mcp:http",
     "test:media": "pnpm exec tsx test/continuous-test-suite-media-gen.ts",
     "test:media-registry-collisions": "pnpm exec tsx test/continuous-test-suite-media-registry-collisions.ts",
@@ -154,7 +155,7 @@
     "// CI tier — fast, no live AI calls, safe for every commit (test:unit; also see the separate provider-safety-net CI job, which runs build + test:providers-mocked + test:provider-structure + test:error-classifier-contract on every PR)": "",
     "test:tool-routing": "pnpm exec tsx test/continuous-test-suite-tool-routing.ts",
     "test:tool-routing-semantic": "pnpm exec tsx test/continuous-test-suite-tool-routing-semantic.ts",
-    "test:unit": "pnpm run test:bugfixes && pnpm run test:mcp:infra && pnpm run test:mcp:spans && pnpm run test:tool-routing && pnpm run test:tool-routing-cli && pnpm run test:tool-dedup && pnpm run test:model-pool && pnpm run test:classifier-router && pnpm run test:tool-routing-semantic && pnpm run test:mcp-result-cache && pnpm run test:model-not-found-retryable && pnpm run test:archive:security && pnpm run test:office:security && pnpm run test:vector-chroma && pnpm run test:vector-pgvector && pnpm run test:vector-pinecone && pnpm run test:provider-wiring && pnpm run test:docs-mcp",
+    "test:unit": "pnpm run test:bugfixes && pnpm run test:mcp:infra && pnpm run test:mcp:spans && pnpm run test:tool-routing && pnpm run test:tool-routing-cli && pnpm run test:tool-dedup && pnpm run test:model-pool && pnpm run test:classifier-router && pnpm run test:tool-routing-semantic && pnpm run test:mcp-result-cache && pnpm run test:mcp-direct-name-repair && pnpm run test:model-not-found-retryable && pnpm run test:archive:security && pnpm run test:office:security && pnpm run test:vector-chroma && pnpm run test:vector-pgvector && pnpm run test:vector-pinecone && pnpm run test:provider-wiring && pnpm run test:docs-mcp",
     "// CI tier — live providers, runs only when API keys are present (test:credentials and test:dynamic make real provider calls when keys are set, so they live here, not in test:unit; test:matrix, a different suite covering the full provider capability matrix, runs nightly via .github/workflows/live-matrix.yml — test:providers itself is still only wired into test:live, not any GitHub Actions workflow)": "",
     "test:live": "pnpm run test:providers && pnpm run test:mcp:http && pnpm run test:mcp:sdk && pnpm run test:mcp:cli && pnpm run test:observability && pnpm run test:context && pnpm run test:memory && pnpm run test:tool-reliability && pnpm run test:evaluation && pnpm run test:autoresearch && pnpm run test:credentials && pnpm run test:dynamic",
     "// CI tier — product output (image/video/TTS/PPT) — costs $$ per run (not wired into any GitHub Actions workflow as of this comment; run manually or add to live-matrix.yml if nightly coverage is needed)": "",