@juspay/neurolink 9.74.0 → 9.76.0

package/dist/cli/factories/commandFactory.js

@@ -10,6 +10,7 @@ import { checkRedisAvailability } from "../../lib/utils/conversationMemory.js";
 import { normalizeEvaluationData } from "../../lib/utils/evaluationUtils.js";
 import { logger } from "../../lib/utils/logger.js";
 import { createThinkingConfigFromRecord } from "../../lib/utils/thinkingConfig.js";
+import { buildToolRoutingConfigFromCli } from "../utils/toolRoutingFlags.js";
 import { configManager } from "../commands/config.js";
 import { MCPCommandFactory } from "../commands/mcp.js";
 import { ModelsCommandFactory } from "../commands/models.js";
@@ -540,6 +541,42 @@ export class CLICommandFactory {
             description: "Thinking level for extended reasoning (Anthropic Claude, Gemini 2.5+, Gemini 3): minimal, low, medium, high",
             choices: ["minimal", "low", "medium", "high"],
         },
+        // Tool-routing options
+        toolRouting: {
+            type: "boolean",
+            description: "Enable pre-call per-turn tool routing (narrows MCP tools by relevance).",
+        },
+        toolRoutingTimeout: {
+            type: "number",
+            description: "Router LLM hard timeout in milliseconds.",
+            alias: "tool-routing-timeout",
+        },
+        toolRoutingRouterProvider: {
+            type: "string",
+            description: "Override the provider used for the router LLM call.",
+            alias: "tool-routing-router-provider",
+        },
+        toolRoutingRouterModel: {
+            type: "string",
+            description: "Override the model used for the router LLM call.",
+            alias: "tool-routing-router-model",
+        },
+        toolRoutingRouterRegion: {
+            type: "string",
+            description: "Override the region used for the router LLM call.",
+            alias: "tool-routing-router-region",
+        },
+        toolRoutingAlwaysInclude: {
+            type: "array",
+            description: "Server ids whose tools are always kept and never offered to the router (repeatable).",
+            alias: "tool-routing-always-include",
+            string: true,
+        },
+        toolRoutingServers: {
+            type: "string",
+            description: "Path to a JSON file OR inline JSON array of {id, description} server descriptors for the routable catalog.",
+            alias: "tool-routing-servers",
+        },
         region: {
             type: "string",
             description: "Vertex AI region (e.g., us-central1, europe-west1, asia-northeast1)",
@@ -821,6 +858,16 @@ export class CLICommandFactory {
             authMethod: argv.authMethod,
             subscriptionTier: argv.subscriptionTier,
             enableBeta: argv.enableBeta,
+            // Tool-routing flags — constructor-level config, not a per-call option.
+            // Passed through the options bag so handlers can inject into the SDK
+            // instance before the first getOrCreateNeuroLink() call.
+            toolRouting: argv.toolRouting,
+            toolRoutingTimeout: argv.toolRoutingTimeout,
+            toolRoutingRouterProvider: argv.toolRoutingRouterProvider,
+            toolRoutingRouterModel: argv.toolRoutingRouterModel,
+            toolRoutingRouterRegion: argv.toolRoutingRouterRegion,
+            toolRoutingAlwaysInclude: argv.toolRoutingAlwaysInclude,
+            toolRoutingServers: argv.toolRoutingServers,
         };
     }
     /**
@@ -2217,6 +2264,11 @@ export class CLICommandFactory {
                 }
                 return;
             }
+            // Inject tool-routing config into the SDK instance before constructing it.
+            const toolRoutingConfig = buildToolRoutingConfigFromCli(options);
+            if (toolRoutingConfig) {
+                globalSession.setToolRoutingConfig(toolRoutingConfig);
+            }
             // Initialize SDK and session
             const sdk = globalSession.getOrCreateNeuroLink();
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
@@ -2447,6 +2499,11 @@ export class CLICommandFactory {
      * Execute real streaming with timeout handling
      */
     static async executeRealStream(argv, options, inputText, contextMetadata) {
+        // Inject tool-routing config into the SDK instance before constructing it.
+        const toolRoutingConfig = buildToolRoutingConfigFromCli(options);
+        if (toolRoutingConfig) {
+            globalSession.setToolRoutingConfig(toolRoutingConfig);
+        }
         const sdk = globalSession.getOrCreateNeuroLink();
         const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
         const enhancedOptions = { ...options, ...sessionVariables };
@@ -2923,6 +2980,11 @@ export class CLICommandFactory {
                 logger.always(chalk.blue(`📦 Processing ${prompts.length} prompts...\n`));
             }
             const results = [];
+            // Inject tool-routing config into the SDK instance before constructing it.
+            const toolRoutingConfig = buildToolRoutingConfigFromCli(options);
+            if (toolRoutingConfig) {
+                globalSession.setToolRoutingConfig(toolRoutingConfig);
+            }
             const sdk = globalSession.getOrCreateNeuroLink();
             const sessionVariables = CLICommandFactory.normalizeLoopSessionVariables(globalSession.getSessionVariables());
             const enhancedOptions = { ...options, ...sessionVariables };

package/dist/cli/utils/toolRoutingFlags.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CLI helper: parse --tool-routing-* flags into a ToolRoutingConfig.
+ *
+ * This module is intentionally side-effect-free so it can be unit-tested
+ * without a running NeuroLink instance.
+ */
+import type { CliToolRoutingFlags, ToolRoutingConfig } from "../../lib/types/index.js";
+/**
+ * Build a {@link ToolRoutingConfig} from the parsed CLI flags.
+ *
+ * Returns `undefined` when `--tool-routing` is absent or false, so callers
+ * can skip the setter entirely with a simple truthiness check — behaviour is
+ * identical to routing being disabled.
+ *
+ * `--tool-routing-servers` is parsed permissively:
+ * - If the value looks like an existing file path, the file is read and JSON-parsed.
+ * - Otherwise the value is treated as an inline JSON string.
+ * - On any parse error a warning is logged and `servers` is omitted (fail open).
+ */
+export declare function buildToolRoutingConfigFromCli(flags: CliToolRoutingFlags & Record<string, unknown>): ToolRoutingConfig | undefined;

package/dist/cli/utils/toolRoutingFlags.js

@@ -0,0 +1,115 @@
+/**
+ * CLI helper: parse --tool-routing-* flags into a ToolRoutingConfig.
+ *
+ * This module is intentionally side-effect-free so it can be unit-tested
+ * without a running NeuroLink instance.
+ */
+import fs from "node:fs";
+import { logger } from "../../lib/utils/logger.js";
+/**
+ * Build a {@link ToolRoutingConfig} from the parsed CLI flags.
+ *
+ * Returns `undefined` when `--tool-routing` is absent or false, so callers
+ * can skip the setter entirely with a simple truthiness check — behaviour is
+ * identical to routing being disabled.
+ *
+ * `--tool-routing-servers` is parsed permissively:
+ * - If the value looks like an existing file path, the file is read and JSON-parsed.
+ * - Otherwise the value is treated as an inline JSON string.
+ * - On any parse error a warning is logged and `servers` is omitted (fail open).
+ */
+export function buildToolRoutingConfigFromCli(flags) {
+    if (!flags.toolRouting) {
+        return undefined;
+    }
+    const config = { enabled: true };
+    if (flags.toolRoutingTimeout !== undefined) {
+        const t = flags.toolRoutingTimeout;
+        if (Number.isFinite(t) && t > 0) {
+            config.timeoutMs = t;
+        }
+        else {
+            logger.warn(`[tool-routing] --tool-routing-timeout value ${String(t)} is not a positive finite number; ignoring (SDK default applies).`);
+        }
+    }
+    const hasRouterProvider = typeof flags.toolRoutingRouterProvider === "string";
+    const hasRouterModel = typeof flags.toolRoutingRouterModel === "string";
+    const hasRouterRegion = typeof flags.toolRoutingRouterRegion === "string";
+    if (hasRouterProvider || hasRouterModel || hasRouterRegion) {
+        config.routerModel = {
+            ...(hasRouterProvider && {
+                provider: flags.toolRoutingRouterProvider,
+            }),
+            ...(hasRouterModel && {
+                model: flags.toolRoutingRouterModel,
+            }),
+            ...(hasRouterRegion && {
+                region: flags.toolRoutingRouterRegion,
+            }),
+        };
+    }
+    if (Array.isArray(flags.toolRoutingAlwaysInclude) &&
+        flags.toolRoutingAlwaysInclude.length > 0) {
+        config.alwaysIncludeServerIds = flags.toolRoutingAlwaysInclude;
+    }
+    if (typeof flags.toolRoutingServers === "string" &&
+        flags.toolRoutingServers.trim() !== "") {
+        config.servers = parseServersFlag(flags.toolRoutingServers);
+    }
+    return config;
+}
+// Trust model: --tool-routing-servers is a local, user-supplied CLI flag.
+// The invoking user already holds the process's OS permissions, so absolute
+// and home-dir config paths are fully supported — there is no cross-trust-
+// boundary to enforce.  The caps below are a robustness guard against
+// accidentally pointing at a huge file (e.g. a log or binary) that would
+// silently OOM the process or stall the CLI, not a security boundary.
+const MAX_SERVERS_INPUT_BYTES = 1_000_000; // 1 MB
+const MAX_SERVERS_ENTRIES = 1_000;
+/**
+ * Parse the `--tool-routing-servers` value.
+ *
+ * Tries file-path first (if the string exists on disk), then inline JSON.
+ * Logs a warning and returns `undefined` on any error (fail open).
+ */
+function parseServersFlag(value) {
+    try {
+        // File-path branch: resolve relative to cwd, check existence.
+        const resolved = fs.existsSync(value) ? value : null;
+        if (resolved !== null) {
+            const { size } = fs.statSync(resolved);
+            if (size > MAX_SERVERS_INPUT_BYTES) {
+                logger.warn(`[tool-routing] --tool-routing-servers file exceeds ${MAX_SERVERS_INPUT_BYTES} bytes (got ${size}); ignoring to avoid excessive memory use.`);
+                return undefined;
+            }
+        }
+        else if (Buffer.byteLength(value, "utf8") > MAX_SERVERS_INPUT_BYTES) {
+            logger.warn(`[tool-routing] --tool-routing-servers inline JSON exceeds ${MAX_SERVERS_INPUT_BYTES} bytes; ignoring to avoid excessive memory use.`);
+            return undefined;
+        }
+        const jsonText = resolved ? fs.readFileSync(resolved, "utf8") : value;
+        const parsed = JSON.parse(jsonText);
+        if (!Array.isArray(parsed)) {
+            logger.warn("[tool-routing] --tool-routing-servers must be a JSON array; ignoring.");
+            return undefined;
+        }
+        // Validate shape loosely — only keep entries with id + description strings.
+        const valid = parsed.filter((entry) => typeof entry === "object" &&
+            entry !== null &&
+            typeof entry.id === "string" &&
+            typeof entry.description === "string");
+        if (valid.length !== parsed.length) {
+            logger.warn(`[tool-routing] ${parsed.length - valid.length} server descriptor(s) skipped — each must have string "id" and "description" fields.`);
+        }
+        if (valid.length > MAX_SERVERS_ENTRIES) {
+            logger.warn(`[tool-routing] --tool-routing-servers contains ${valid.length} entries; truncating to ${MAX_SERVERS_ENTRIES} to prevent pathological inputs.`);
+            return valid.slice(0, MAX_SERVERS_ENTRIES);
+        }
+        return valid.length > 0 ? valid : undefined;
+    }
+    catch (err) {
+        logger.warn(`[tool-routing] Failed to parse --tool-routing-servers: ${err.message}. Omitting servers (fail open).`);
+        return undefined;
+    }
+}
+//# sourceMappingURL=toolRoutingFlags.js.map

package/dist/core/baseProvider.js

@@ -13,6 +13,7 @@ import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { getKeyCount, getKeysAsString } from "../utils/transformationUtils.js";
 import { TTSProcessor } from "../utils/ttsProcessor.js";
 import { executeVideoAnalysis, hasVideoFrames, } from "../utils/videoAnalysisProcessor.js";
+import { dedupeTools } from "./toolDedup.js";
 import { GenerationHandler } from "./modules/GenerationHandler.js";
 // Import modules for composition
 import { MessageBuilder } from "./modules/MessageBuilder.js";
@@ -538,13 +539,19 @@ export class BaseProvider {
      * If excludeTools is set, matching tools are removed. excludeTools is applied after toolFilter.
      */
     applyToolFiltering(tools, options) {
-        if ((!options.toolFilter || options.toolFilter.length === 0) &&
-            (!options.excludeTools || options.excludeTools.length === 0)) {
+        const hasWhitelist = options.toolFilter && options.toolFilter.length > 0;
+        const hasDenylist = options.excludeTools && options.excludeTools.length > 0;
+        // Check whether the dedup pass is requested — even when no whitelist/
+        // denylist is set we still need to run the dedup pass if enabled.
+        const dedupConfig = this.neurolink?.getToolDedupConfig();
+        const hasDedupEnabled = dedupConfig !== undefined && dedupConfig.enabled === true;
+        if (!hasWhitelist && !hasDenylist && !hasDedupEnabled) {
+            // Fast path: nothing to do.
             return tools;
         }
         const beforeCount = Object.keys(tools).length;
         let filtered = { ...tools };
-        if (options.toolFilter && options.toolFilter.length > 0) {
+        if (hasWhitelist) {
             const allowSet = new Set(options.toolFilter);
             const result = {};
             for (const [name, tool] of Object.entries(filtered)) {
@@ -554,7 +561,7 @@ export class BaseProvider {
             }
             filtered = result;
         }
-        if (options.excludeTools && options.excludeTools.length > 0) {
+        if (hasDenylist) {
             const denySet = new Set(options.excludeTools);
             for (const name of Object.keys(filtered)) {
                 if (denySet.has(name)) {
@@ -572,6 +579,24 @@ export class BaseProvider {
                 excludeTools: options.excludeTools,
             });
         }
+        // Opt-in signature dedup — runs AFTER whitelist/blacklist filtering and
+        // BEFORE the tool set reaches the provider call.  Fails open: any error
+        // inside dedupeTools returns the original filtered set unchanged.
+        if (dedupConfig !== undefined && dedupConfig.enabled) {
+            const { tools: dedupedTools, removed } = dedupeTools(filtered, dedupConfig);
+            if (removed.length > 0 && logger.shouldLog("debug")) {
+                logger.debug(`Tool signature dedup removed duplicates`, {
+                    provider: this.providerName,
+                    removedCount: removed.length,
+                    removed: removed.map((r) => ({
+                        name: r.name,
+                        duplicateOf: r.duplicateOf,
+                        similarity: r.similarity,
+                    })),
+                });
+            }
+            return dedupedTools;
+        }
         return filtered;
     }
     /**

package/dist/core/toolDedup.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tool-signature deduplication — pure module, no I/O, no side effects.
+ *
+ * ## Algorithm
+ *
+ * `computeToolSignature` builds a canonical, order-insensitive string from:
+ *   1. The tool's name (exact, case-preserved).
+ *   2. A normalised description: lowercased, all whitespace runs collapsed to a
+ *      single space, leading/trailing whitespace stripped.
+ *   3. A sorted, deduplicated list of JSON-schema property names (top-level
+ *      `properties` keys from `inputSchema`).  If the schema exposes a `type`
+ *      field on each property, that type string is appended as `name:type`.
+ *
+ * `dedupeTools` clusters tools by pairwise token-set Jaccard similarity:
+ *
+ *   Jaccard(A, B) = |A ∩ B| / |A ∪ B|
+ *
+ * where A and B are the _sets_ of whitespace-split tokens from each tool's
+ * canonical signature.  This is deterministic, symmetric, and independent of
+ * token ordering — making it robust to minor rewording while being fast (O(n²)
+ * in the number of tools, which is bounded in practice by provider limits).
+ *
+ * The first tool encountered in stable input-iteration order becomes the
+ * cluster representative; subsequent tools in the same cluster are dropped.
+ */
+import type { Tool } from "../types/index.js";
+import type { ToolDedupConfig, ToolDedupResult } from "../types/index.js";
+/**
+ * Build a canonical, order-insensitive signature string for a named tool.
+ *
+ * The signature is composed of:
+ *   - the tool's name
+ *   - a normalised description (lowercased, whitespace-collapsed)
+ *   - sorted parameter property names (with types when available)
+ *
+ * Stable regardless of property declaration order in the schema.
+ */
+export declare function computeToolSignature(name: string, tool: Tool): string;
+/**
+ * Collapse near-duplicate tools in a name→Tool record.
+ *
+ * When `options.enabled` is falsy (the default), returns the original record
+ * and an empty `removed` array — byte-for-byte unchanged behaviour.
+ *
+ * When enabled, tools whose token-set Jaccard similarity (over their canonical
+ * signatures) meets or exceeds `options.threshold` (default 0.9) are collapsed
+ * to a single representative (the first in stable iteration order).
+ *
+ * Any exception thrown internally returns the ORIGINAL tool set (fail-open).
+ */
+export declare function dedupeTools<T extends Tool>(tools: Record<string, T>, options: ToolDedupConfig): ToolDedupResult<Record<string, T>>;

package/dist/core/toolDedup.js

@@ -0,0 +1,193 @@
+/**
+ * Tool-signature deduplication — pure module, no I/O, no side effects.
+ *
+ * ## Algorithm
+ *
+ * `computeToolSignature` builds a canonical, order-insensitive string from:
+ *   1. The tool's name (exact, case-preserved).
+ *   2. A normalised description: lowercased, all whitespace runs collapsed to a
+ *      single space, leading/trailing whitespace stripped.
+ *   3. A sorted, deduplicated list of JSON-schema property names (top-level
+ *      `properties` keys from `inputSchema`).  If the schema exposes a `type`
+ *      field on each property, that type string is appended as `name:type`.
+ *
+ * `dedupeTools` clusters tools by pairwise token-set Jaccard similarity:
+ *
+ *   Jaccard(A, B) = |A ∩ B| / |A ∪ B|
+ *
+ * where A and B are the _sets_ of whitespace-split tokens from each tool's
+ * canonical signature.  This is deterministic, symmetric, and independent of
+ * token ordering — making it robust to minor rewording while being fast (O(n²)
+ * in the number of tools, which is bounded in practice by provider limits).
+ *
+ * The first tool encountered in stable input-iteration order becomes the
+ * cluster representative; subsequent tools in the same cluster are dropped.
+ */
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extract top-level property names (and optionally their types) from a JSON
+ * Schema-shaped `inputSchema`.  Returns a sorted, stable list.
+ *
+ * The `inputSchema` on a `Tool` is typed as `FlexibleSchema<INPUT>` (opaque at
+ * runtime), so we access it via index to avoid casting.
+ */
+function extractSchemaTokens(inputSchema) {
+    if (!inputSchema) {
+        return [];
+    }
+    // FlexibleSchema may be a Zod schema, a jsonSchema() wrapper, or a plain
+    // JSON Schema object.  All three expose `jsonSchema` or fall through to the
+    // raw object.  We look for the plain JSON Schema `properties` key.
+    const schema = inputSchema;
+    // Vercel AI SDK wraps plain schemas in { jsonSchema: {...}, ... }
+    const rawSchema = schema["jsonSchema"] !== undefined
+        ? schema["jsonSchema"]
+        : schema;
+    const properties = rawSchema["properties"];
+    if (!properties || typeof properties !== "object" || properties === null) {
+        return [];
+    }
+    const tokens = [];
+    const props = properties;
+    for (const propName of Object.keys(props)) {
+        const propDef = props[propName];
+        if (propDef && typeof propDef === "object" && propDef !== null) {
+            const t = propDef["type"];
+            tokens.push(typeof t === "string" ? `${propName}:${t}` : propName);
+        }
+        else {
+            tokens.push(propName);
+        }
+    }
+    return tokens.sort();
+}
+/**
+ * Normalise a description string: lowercase, collapse whitespace, strip ends.
+ */
+function normaliseDescription(desc) {
+    if (!desc) {
+        return "";
+    }
+    return desc.toLowerCase().replace(/\s+/g, " ").trim();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Build a canonical, order-insensitive signature string for a named tool.
+ *
+ * The signature is composed of:
+ *   - the tool's name
+ *   - a normalised description (lowercased, whitespace-collapsed)
+ *   - sorted parameter property names (with types when available)
+ *
+ * Stable regardless of property declaration order in the schema.
+ */
+export function computeToolSignature(name, tool) {
+    const descPart = normaliseDescription(tool.description);
+    const schemaParts = extractSchemaTokens(tool.inputSchema);
+    // Pipe-separated sections keep tokens within each section unambiguous.
+    return [name, descPart, schemaParts.join(",")].join("|");
+}
+/**
+ * Compute the token-set Jaccard similarity between two signature strings.
+ *
+ *   Jaccard(A, B) = |A ∩ B| / |A ∪ B|
+ *
+ * Splits on whitespace and also on the pipe/comma delimiters used by
+ * `computeToolSignature` so that structural differences (e.g. a parameter
+ * missing from one tool) are properly reflected.
+ */
+function jaccardSimilarity(sigA, sigB) {
+    const tokenise = (s) => new Set(s.split(/[\s|,]+/).filter((t) => t.length > 0));
+    const setA = tokenise(sigA);
+    const setB = tokenise(sigB);
+    if (setA.size === 0 && setB.size === 0) {
+        return 1;
+    }
+    if (setA.size === 0 || setB.size === 0) {
+        return 0;
+    }
+    let intersection = 0;
+    for (const token of setA) {
+        if (setB.has(token)) {
+            intersection += 1;
+        }
+    }
+    const union = setA.size + setB.size - intersection;
+    return intersection / union;
+}
+/**
+ * Collapse near-duplicate tools in a name→Tool record.
+ *
+ * When `options.enabled` is falsy (the default), returns the original record
+ * and an empty `removed` array — byte-for-byte unchanged behaviour.
+ *
+ * When enabled, tools whose token-set Jaccard similarity (over their canonical
+ * signatures) meets or exceeds `options.threshold` (default 0.9) are collapsed
+ * to a single representative (the first in stable iteration order).
+ *
+ * Any exception thrown internally returns the ORIGINAL tool set (fail-open).
+ */
+export function dedupeTools(tools, options) {
+    const noOp = { tools, removed: [] };
+    if (!options.enabled) {
+        return noOp;
+    }
+    try {
+        const rawThreshold = options.threshold ?? 0.9;
+        const threshold = Math.min(1, Math.max(0, rawThreshold));
+        const entries = Object.entries(tools);
+        if (entries.length <= 1) {
+            return noOp;
+        }
+        // Pre-compute signatures once.
+        const signatures = new Map();
+        for (const [name, tool] of entries) {
+            signatures.set(name, computeToolSignature(name, tool));
+        }
+        // representative[toolName] = name of the cluster representative.
+        // Tools not yet assigned to a cluster act as their own representative.
+        const representativeOf = new Map();
+        for (const [nameA] of entries) {
+            if (representativeOf.has(nameA)) {
+                // Already absorbed into another cluster.
+                continue;
+            }
+            const sigA = signatures.get(nameA) ?? "";
+            for (const [nameB] of entries) {
+                if (nameA === nameB || representativeOf.has(nameB)) {
+                    continue;
+                }
+                const sigB = signatures.get(nameB) ?? "";
+                const sim = jaccardSimilarity(sigA, sigB);
+                if (sim >= threshold) {
+                    representativeOf.set(nameB, nameA);
+                }
+            }
+        }
+        if (representativeOf.size === 0) {
+            return noOp;
+        }
+        const dedupedTools = {};
+        const removed = [];
+        for (const [name, tool] of entries) {
+            const rep = representativeOf.get(name);
+            if (rep !== undefined) {
+                // Compute similarity again to include in the removed record.
+                const sim = jaccardSimilarity(signatures.get(name) ?? "", signatures.get(rep) ?? "");
+                removed.push({ name, duplicateOf: rep, similarity: sim });
+            }
+            else {
+                dedupedTools[name] = tool;
+            }
+        }
+        return { tools: dedupedTools, removed };
+    }
+    catch {
+        // Fail open — return the original set.
+        return noOp;
+    }
+}

package/dist/index.d.ts

@@ -214,6 +214,7 @@ export declare function createBestAIProvider(requestedProvider?: string, modelNa
  * ```
  */
 export { CircuitBreakerManager, calculateExpiresAt, createMCPServer, createOAuthProviderFromConfig, DEFAULT_HTTP_RETRY_CONFIG, DEFAULT_RATE_LIMIT_CONFIG, executeMCP, FileTokenStorage, getMCPStats, getServerInfo, globalCircuitBreakerManager, globalRateLimiterManager, HTTPRateLimiter, InMemoryTokenStorage, initializeMCPEcosystem, isRetryableHTTPError, isRetryableStatusCode, isTokenExpired, listMCPs, CircuitBreakerOpenError, MCPCircuitBreaker, mcpLogger, NeuroLinkOAuthProvider, RateLimiterManager, validateServerTools, validateTool as validateMCPTool, withHTTPRetry, MCPToolRegistry, ExternalServerManager, MCPClientFactory, ToolRouter, createToolRouter, DEFAULT_ROUTER_CONFIG, ToolCache, createToolCache, DEFAULT_CACHE_CONFIG, ToolResultCache, createToolResultCache, RequestBatcher, ToolCallBatcher, createRequestBatcher, createToolCallBatcher, DEFAULT_BATCH_CONFIG, inferAnnotations, createAnnotatedTool, validateAnnotations, filterToolsByAnnotations, mergeAnnotations, getAnnotationSummary, requiresConfirmation, isSafeToRetry, getToolSafetyLevel, ElicitationManager, globalElicitationManager, EnhancedToolDiscovery, MCPRegistryClient, globalMCPRegistryClient, getWellKnownServer, getAllWellKnownServers, MCPServerBase, MultiServerManager, globalMultiServerManager, AgentExposureManager, exposeAgentAsTool, exposeAgentsAsTools, exposeWorkflowAsTool, exposeWorkflowsAsTools, globalAgentExposureManager, ServerCapabilitiesManager, createTextResource, createJsonResource, createPrompt, neuroLinkToolToMCP, mcpToolToNeuroLink, batchConvertToMCP, batchConvertToNeuroLink, sanitizeToolName, validateToolName, createToolFromFunction, mcpProtocolToolToServerTool, serverToolToMCPProtocol, TOOL_COMPATIBILITY, ToolIntegrationManager, globalToolIntegrationManager, wrapToolWithElicitation, wrapToolsWithElicitation, createElicitationContext, confirmationMiddleware, validationMiddleware, loggingMiddleware, createRetryMiddleware, createTimeoutMiddleware, createToolMiddlewareChain, ElicitationProtocolAdapter, globalElicitationProtocol, isElicitationProtocolMessage, protocolMessageToElicitation, elicitationResponseToProtocol, createElicitationRequest, createElicitationResponse, createElicitationCancel, createTextInputRequest, createSelectRequest, createConfirmationRequest, createFormRequest, } from "./mcp/index.js";
+export { computeToolSignature, dedupeTools } from "./core/toolDedup.js";
 export { logger } from "./utils/logger.js";
 export { getPoolStats } from "./utils/redis.js";
 export { ToolRoutingCache } from "./core/toolRoutingCache.js";

package/dist/index.js

@@ -354,6 +354,8 @@ neuroLinkToolToMCP, mcpToolToNeuroLink, batchConvertToMCP, batchConvertToNeuroLi
 ToolIntegrationManager, globalToolIntegrationManager, wrapToolWithElicitation, wrapToolsWithElicitation, createElicitationContext, confirmationMiddleware, validationMiddleware, loggingMiddleware, createRetryMiddleware, createTimeoutMiddleware, createToolMiddlewareChain, 
 // MCP Enhancements - Elicitation Protocol
 ElicitationProtocolAdapter, globalElicitationProtocol, isElicitationProtocolMessage, protocolMessageToElicitation, elicitationResponseToProtocol, createElicitationRequest, createElicitationResponse, createElicitationCancel, createTextInputRequest, createSelectRequest, createConfirmationRequest, createFormRequest, } from "./mcp/index.js";
+// Tool signature deduplication utilities (opt-in, fail-open)
+export { computeToolSignature, dedupeTools } from "./core/toolDedup.js";
 export { logger } from "./utils/logger.js";
 export { getPoolStats } from "./utils/redis.js";
 // Pre-call tool routing cache (ITEM C: LRU+TTL cache + session stickiness)

package/dist/lib/core/baseProvider.js

@@ -13,6 +13,7 @@ import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { getKeyCount, getKeysAsString } from "../utils/transformationUtils.js";
 import { TTSProcessor } from "../utils/ttsProcessor.js";
 import { executeVideoAnalysis, hasVideoFrames, } from "../utils/videoAnalysisProcessor.js";
+import { dedupeTools } from "./toolDedup.js";
 import { GenerationHandler } from "./modules/GenerationHandler.js";
 // Import modules for composition
 import { MessageBuilder } from "./modules/MessageBuilder.js";
@@ -538,13 +539,19 @@ export class BaseProvider {
      * If excludeTools is set, matching tools are removed. excludeTools is applied after toolFilter.
      */
     applyToolFiltering(tools, options) {
-        if ((!options.toolFilter || options.toolFilter.length === 0) &&
-            (!options.excludeTools || options.excludeTools.length === 0)) {
+        const hasWhitelist = options.toolFilter && options.toolFilter.length > 0;
+        const hasDenylist = options.excludeTools && options.excludeTools.length > 0;
+        // Check whether the dedup pass is requested — even when no whitelist/
+        // denylist is set we still need to run the dedup pass if enabled.
+        const dedupConfig = this.neurolink?.getToolDedupConfig();
+        const hasDedupEnabled = dedupConfig !== undefined && dedupConfig.enabled === true;
+        if (!hasWhitelist && !hasDenylist && !hasDedupEnabled) {
+            // Fast path: nothing to do.
             return tools;
         }
         const beforeCount = Object.keys(tools).length;
         let filtered = { ...tools };
-        if (options.toolFilter && options.toolFilter.length > 0) {
+        if (hasWhitelist) {
             const allowSet = new Set(options.toolFilter);
             const result = {};
             for (const [name, tool] of Object.entries(filtered)) {
@@ -554,7 +561,7 @@ export class BaseProvider {
             }
             filtered = result;
         }
-        if (options.excludeTools && options.excludeTools.length > 0) {
+        if (hasDenylist) {
             const denySet = new Set(options.excludeTools);
             for (const name of Object.keys(filtered)) {
                 if (denySet.has(name)) {
@@ -572,6 +579,24 @@ export class BaseProvider {
                 excludeTools: options.excludeTools,
             });
         }
+        // Opt-in signature dedup — runs AFTER whitelist/blacklist filtering and
+        // BEFORE the tool set reaches the provider call.  Fails open: any error
+        // inside dedupeTools returns the original filtered set unchanged.
+        if (dedupConfig !== undefined && dedupConfig.enabled) {
+            const { tools: dedupedTools, removed } = dedupeTools(filtered, dedupConfig);
+            if (removed.length > 0 && logger.shouldLog("debug")) {
+                logger.debug(`Tool signature dedup removed duplicates`, {
+                    provider: this.providerName,
+                    removedCount: removed.length,
+                    removed: removed.map((r) => ({
+                        name: r.name,
+                        duplicateOf: r.duplicateOf,
+                        similarity: r.similarity,
+                    })),
+                });
+            }
+            return dedupedTools;
+        }
         return filtered;
     }
     /**