@juspay/neurolink 9.90.0 → 9.91.1

package/dist/core/baseProvider.d.ts

@@ -77,10 +77,44 @@ export declare abstract class BaseProvider implements AIProvider {
     private executeFakeStreaming;
     /**
      * Apply per-call tool filtering (whitelist/blacklist) to a tools record.
-     * If toolFilter is set, only tools whose names are in the list are kept.
-     * If excludeTools is set, matching tools are removed. excludeTools is applied after toolFilter.
-     */
+     *
+     * All filtering surfaces are merged into one ResolvedToolPolicy by
+     * `resolveToolPolicy()` — per-call `toolFilter` (whitelist),
+     * `enabledToolNames` (merged into the whitelist, as its docs always
+     * promised), `excludeTools` (denylist, applied after the whitelist), and
+     * the instance-level `tools` config (enabled/include/exclude, `*` globs) —
+     * then applied by `applyToolGate()`. This is the single filter semantics
+     * for every generate/stream path.
+     */
+    private getToolPolicy;
     private applyToolFiltering;
+    /**
+     * Deterministic name-sorted key order. External MCP servers connect and
+     * discover in parallel, so insertion order varies across process restarts;
+     * providers serialize this record in key order (and Anthropic pins its
+     * cache_control breakpoint to the LAST tool), so an unstable order silently
+     * busts provider prompt caches. Runs AFTER the dedup pass — dedup's
+     * keep-first policy must see phase order (built-ins first) so duplicate
+     * winners don't flip when an MCP tool name sorts earlier.
+     */
+    private sortToolRecord;
+    /**
+     * On-demand discovery (`tools.discovery: true`): defer external MCP tool
+     * schemas behind one `search_tools` meta-tool. Built-in tools, per-call
+     * tools, explicitly whitelisted tools, and session-pinned (previously
+     * discovered) tools always stay hot. No-op when discovery is off — with a
+     * one-time WARN when the catalog is large enough that selection accuracy
+     * measurably degrades.
+     */
+    private applyToolDiscovery;
+    private static warnedLargeCatalog;
+    private warnLargeCatalogOnce;
+    /**
+     * 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.
+     */
+    private applyDedupPass;
     /**
      * Prepare generation context including tools and model
      */

package/dist/core/baseProvider.js

@@ -14,6 +14,9 @@ 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 { resolveToolPolicy, toolNameMatcher } from "../tools/toolPolicy.js";
+import { applyToolGate } from "../tools/toolGate.js";
+import { partitionToolsForDiscovery, isDiscoveryMetaTool, LARGE_CATALOG_WARN_THRESHOLD, } from "../tools/toolDiscovery.js";
 import { GenerationHandler } from "./modules/GenerationHandler.js";
 // Import modules for composition
 import { MessageBuilder } from "./modules/MessageBuilder.js";
@@ -535,69 +538,185 @@ export class BaseProvider {
     }
     /**
      * Apply per-call tool filtering (whitelist/blacklist) to a tools record.
-     * If toolFilter is set, only tools whose names are in the list are kept.
-     * If excludeTools is set, matching tools are removed. excludeTools is applied after toolFilter.
+     *
+     * All filtering surfaces are merged into one ResolvedToolPolicy by
+     * `resolveToolPolicy()` — per-call `toolFilter` (whitelist),
+     * `enabledToolNames` (merged into the whitelist, as its docs always
+     * promised), `excludeTools` (denylist, applied after the whitelist), and
+     * the instance-level `tools` config (enabled/include/exclude, `*` globs) —
+     * then applied by `applyToolGate()`. This is the single filter semantics
+     * for every generate/stream path.
      */
+    getToolPolicy(options) {
+        return resolveToolPolicy({
+            options: {
+                toolFilter: options.toolFilter,
+                excludeTools: options.excludeTools,
+                enabledToolNames: options.enabledToolNames,
+            },
+            instanceConfig: this.neurolink?.getToolsConfig(),
+            builtinToolNames: Object.keys(this.directTools ?? {}),
+        });
+    }
     applyToolFiltering(tools, options) {
-        const hasWhitelist = options.toolFilter && options.toolFilter.length > 0;
-        const hasDenylist = options.excludeTools && options.excludeTools.length > 0;
+        const policy = this.getToolPolicy(options);
         // 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 (hasWhitelist) {
-            const allowSet = new Set(options.toolFilter);
-            const result = {};
-            for (const [name, tool] of Object.entries(filtered)) {
-                if (allowSet.has(name)) {
-                    result[name] = tool;
-                }
-            }
-            filtered = result;
-        }
-        if (hasDenylist) {
-            const denySet = new Set(options.excludeTools);
-            for (const name of Object.keys(filtered)) {
-                if (denySet.has(name)) {
-                    delete filtered[name];
-                }
-            }
-        }
+        const filtered = applyToolGate(tools, policy);
         const afterCount = Object.keys(filtered).length;
         if (beforeCount !== afterCount) {
             logger.debug(`Tool filtering applied`, {
                 provider: this.providerName,
                 beforeCount,
                 afterCount,
+                policySources: policy.sources,
                 toolFilter: options.toolFilter,
                 excludeTools: options.excludeTools,
+                enabledToolNames: options.enabledToolNames,
             });
         }
-        // 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,
-                    })),
-                });
+        if (!hasDedupEnabled || dedupConfig === undefined) {
+            return this.sortToolRecord(filtered);
+        }
+        const deduped = this.applyDedupPass(filtered, dedupConfig);
+        // A forced toolChoice must survive dedup: keep-first can collapse the
+        // forced tool into an earlier near-identical signature, and the provider
+        // would then reject the request for naming an unknown tool. Restore it
+        // from the pre-dedup record (whitelisted names are already safe — the
+        // gate runs before dedup, so a whitelist leaves no duplicate to lose to).
+        const forcedName = options.toolChoice?.toolName;
+        if (typeof forcedName === "string" &&
+            !Object.hasOwn(deduped, forcedName) &&
+            Object.hasOwn(filtered, forcedName)) {
+            deduped[forcedName] = filtered[forcedName];
+            logger.debug(`Restored toolChoice-forced tool removed by signature dedup`, { provider: this.providerName, toolName: forcedName });
+        }
+        return this.sortToolRecord(deduped);
+    }
+    /**
+     * Deterministic name-sorted key order. External MCP servers connect and
+     * discover in parallel, so insertion order varies across process restarts;
+     * providers serialize this record in key order (and Anthropic pins its
+     * cache_control breakpoint to the LAST tool), so an unstable order silently
+     * busts provider prompt caches. Runs AFTER the dedup pass — dedup's
+     * keep-first policy must see phase order (built-ins first) so duplicate
+     * winners don't flip when an MCP tool name sorts earlier.
+     */
+    sortToolRecord(tools) {
+        // Null prototype: a tool named "__proto__" must become an own entry, not
+        // a prototype mutation that silently drops the tool.
+        const sorted = Object.create(null);
+        for (const name of Object.keys(tools).sort()) {
+            sorted[name] = tools[name];
+        }
+        return sorted;
+    }
+    /**
+     * On-demand discovery (`tools.discovery: true`): defer external MCP tool
+     * schemas behind one `search_tools` meta-tool. Built-in tools, per-call
+     * tools, explicitly whitelisted tools, and session-pinned (previously
+     * discovered) tools always stay hot. No-op when discovery is off — with a
+     * one-time WARN when the catalog is large enough that selection accuracy
+     * measurably degrades.
+     */
+    async applyToolDiscovery(toolsInput, options) {
+        // Strip a stale meta-tool left by a previous resolution pass (the
+        // stream → generate fallback re-enters resolution with options.tools
+        // already partitioned). Discovery re-partitions against the fresh merged
+        // record below; without this, the collision guard would see our own
+        // meta-tool and skip partitioning, shipping the full catalog AND a stale
+        // search_tools closure. Real user tools named "search_tools" are not
+        // marked and are left untouched.
+        let tools = toolsInput;
+        if (isDiscoveryMetaTool(tools["search_tools"])) {
+            const { search_tools: _stale, ...rest } = tools;
+            tools = rest;
+        }
+        const toolCount = Object.keys(tools).length;
+        const policy = this.getToolPolicy(options);
+        if (!policy.discovery) {
+            if (toolCount > LARGE_CATALOG_WARN_THRESHOLD) {
+                this.warnLargeCatalogOnce(toolCount);
             }
-            return dedupedTools;
+            return tools;
+        }
+        const externalTools = this.neurolink?.getExternalMCPTools() ?? [];
+        if (externalTools.length === 0) {
+            return tools;
+        }
+        // Session pinning requires a caller-provided sessionId. Without one there
+        // is no session identity — pinning to a shared fallback key would leak
+        // one caller's discoveries into every other caller of a shared instance
+        // and monotonically defeat deferral, so pins are simply not persisted.
+        const rawSessionId = options.context?.sessionId;
+        const sessionKey = typeof rawSessionId === "string" && rawSessionId.length > 0
+            ? rawSessionId
+            : typeof rawSessionId === "number"
+                ? String(rawSessionId)
+                : undefined;
+        const pinnedNames = (sessionKey ? this.neurolink?.getDiscoveryPins(sessionKey) : undefined) ??
+            new Set();
+        const perCallNames = new Set(Object.keys(options.tools ?? {}));
+        // Explicitly requested tools stay hot. Allowlist entries may be globs
+        // (e.g. toolFilter: ["github*"]), so match with the same pattern matcher
+        // the gate uses — a Set of pattern STRINGS would defer glob-whitelisted
+        // tools the gate deliberately kept.
+        const explicitPatterns = [
+            ...(options.toolFilter ?? []),
+            ...(options.enabledToolNames ?? []),
+        ];
+        // A toolChoice that forces a named tool must never see that tool
+        // deferred — the provider would reject the request (unknown tool name).
+        const toolChoice = options.toolChoice;
+        if (toolChoice && typeof toolChoice.toolName === "string") {
+            explicitPatterns.push(toolChoice.toolName);
+        }
+        const explicitMatcher = explicitPatterns.length > 0 ? toolNameMatcher(explicitPatterns) : null;
+        const deferrableNames = externalTools
+            .map((t) => t.name)
+            .filter((name) => name in tools &&
+            !perCallNames.has(name) &&
+            !(explicitMatcher ? explicitMatcher(name) : false));
+        return partitionToolsForDiscovery(tools, {
+            deferrableNames,
+            pinnedNames,
+            onHydrate: (names) => {
+                if (sessionKey) {
+                    this.neurolink?.pinDiscoveredTools(sessionKey, names);
+                }
+            },
+        });
+    }
+    static warnedLargeCatalog = false;
+    warnLargeCatalogOnce(toolCount) {
+        if (BaseProvider.warnedLargeCatalog) {
+            return;
+        }
+        BaseProvider.warnedLargeCatalog = true;
+        logger.warn(`[ToolDiscovery] ${toolCount} tools are being sent in full on every request (~${Math.round((toolCount * 175) / 100) / 10}K tokens). Tool-selection accuracy degrades past 30-50 tools — consider enabling on-demand discovery: new NeuroLink({ tools: { discovery: true } })`, { toolCount, provider: this.providerName });
+    }
+    /**
+     * 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.
+     */
+    applyDedupPass(filtered, dedupConfig) {
+        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 filtered;
+        return dedupedTools;
     }
     /**
      * Prepare generation context including tools and model
@@ -613,6 +732,8 @@ export class BaseProvider {
             : {};
         // Apply per-call tool filtering (whitelist/blacklist)
         tools = this.applyToolFiltering(tools, options);
+        // On-demand discovery: defer external MCP schemas behind search_tools
+        tools = await this.applyToolDiscovery(tools, options);
         logger.debug(`Final tools prepared for AI`, {
             provider: this.providerName,
             directTools: getKeyCount(baseTools),
@@ -644,6 +765,8 @@ export class BaseProvider {
         let merged = { ...baseTools, ...externalTools };
         // Apply per-call tool filtering (whitelist/blacklist)
         merged = this.applyToolFiltering(merged, options);
+        // On-demand discovery: defer external MCP schemas behind search_tools
+        merged = await this.applyToolDiscovery(merged, options);
         logger.debug(`Tools prepared for streaming`, {
             provider: this.providerName,
             baseToolCount: Object.keys(baseTools).length,

package/dist/core/modules/GenerationHandler.js

@@ -88,7 +88,13 @@ export class GenerationHandler {
         // Non-Anthropic providers harmlessly ignore unknown providerOptions.
         // Note: The AI SDK Tool type doesn't yet include providerOptions, so we
         // use a type assertion. The Anthropic adapter reads this at runtime.
-        const toolsWithCache = { ...tools };
+        //
+        // Deliberately NOT a clone: the record is call-scoped (built fresh in
+        // BaseProvider.prepareGenerationContext) and the AI SDK re-reads it on
+        // every agent-loop step, so `search_tools` hydration (tools.discovery)
+        // can add discovered tools mid-loop and have them callable on the next
+        // step. A clone would freeze the tool set for the whole call.
+        const toolsWithCache = tools;
         if (isAnthropicProvider &&
             shouldUseTools &&
             Object.keys(toolsWithCache).length > 0) {

package/dist/core/modules/ToolsManager.js

@@ -258,6 +258,11 @@ export class ToolsManager {
                         `... and ${toolNames.length - 10} more`,
                     ],
             });
+            // NOTE: insertion order here is phase order (direct → custom →
+            // external MCP), which the signature-dedup pass depends on (keep-first
+            // must prefer built-in implementations). Deterministic name-sorting
+            // for prompt-cache stability happens AFTER filtering+dedup, in
+            // BaseProvider.applyToolFiltering.
             return tools;
         });
     }

package/dist/core/toolDedup.js

@@ -171,7 +171,10 @@ export function dedupeTools(tools, options) {
         if (representativeOf.size === 0) {
             return noOp;
         }
-        const dedupedTools = {};
+        // Null prototype: a tool named "__proto__" must become an own entry,
+        // not a prototype mutation that silently drops it (mirrors the tool
+        // records built in BaseProvider.sortToolRecord / applyToolGate).
+        const dedupedTools = Object.create(null);
         const removed = [];
         for (const [name, tool] of entries) {
             const rep = representativeOf.get(name);

package/dist/lib/core/baseProvider.d.ts

@@ -77,10 +77,44 @@ export declare abstract class BaseProvider implements AIProvider {
     private executeFakeStreaming;
     /**
      * Apply per-call tool filtering (whitelist/blacklist) to a tools record.
-     * If toolFilter is set, only tools whose names are in the list are kept.
-     * If excludeTools is set, matching tools are removed. excludeTools is applied after toolFilter.
-     */
+     *
+     * All filtering surfaces are merged into one ResolvedToolPolicy by
+     * `resolveToolPolicy()` — per-call `toolFilter` (whitelist),
+     * `enabledToolNames` (merged into the whitelist, as its docs always
+     * promised), `excludeTools` (denylist, applied after the whitelist), and
+     * the instance-level `tools` config (enabled/include/exclude, `*` globs) —
+     * then applied by `applyToolGate()`. This is the single filter semantics
+     * for every generate/stream path.
+     */
+    private getToolPolicy;
     private applyToolFiltering;
+    /**
+     * Deterministic name-sorted key order. External MCP servers connect and
+     * discover in parallel, so insertion order varies across process restarts;
+     * providers serialize this record in key order (and Anthropic pins its
+     * cache_control breakpoint to the LAST tool), so an unstable order silently
+     * busts provider prompt caches. Runs AFTER the dedup pass — dedup's
+     * keep-first policy must see phase order (built-ins first) so duplicate
+     * winners don't flip when an MCP tool name sorts earlier.
+     */
+    private sortToolRecord;
+    /**
+     * On-demand discovery (`tools.discovery: true`): defer external MCP tool
+     * schemas behind one `search_tools` meta-tool. Built-in tools, per-call
+     * tools, explicitly whitelisted tools, and session-pinned (previously
+     * discovered) tools always stay hot. No-op when discovery is off — with a
+     * one-time WARN when the catalog is large enough that selection accuracy
+     * measurably degrades.
+     */
+    private applyToolDiscovery;
+    private static warnedLargeCatalog;
+    private warnLargeCatalogOnce;
+    /**
+     * 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.
+     */
+    private applyDedupPass;
     /**
      * Prepare generation context including tools and model
      */

package/dist/lib/core/baseProvider.js

@@ -14,6 +14,9 @@ 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 { resolveToolPolicy, toolNameMatcher } from "../tools/toolPolicy.js";
+import { applyToolGate } from "../tools/toolGate.js";
+import { partitionToolsForDiscovery, isDiscoveryMetaTool, LARGE_CATALOG_WARN_THRESHOLD, } from "../tools/toolDiscovery.js";
 import { GenerationHandler } from "./modules/GenerationHandler.js";
 // Import modules for composition
 import { MessageBuilder } from "./modules/MessageBuilder.js";
@@ -535,69 +538,185 @@ export class BaseProvider {
     }
     /**
      * Apply per-call tool filtering (whitelist/blacklist) to a tools record.
-     * If toolFilter is set, only tools whose names are in the list are kept.
-     * If excludeTools is set, matching tools are removed. excludeTools is applied after toolFilter.
+     *
+     * All filtering surfaces are merged into one ResolvedToolPolicy by
+     * `resolveToolPolicy()` — per-call `toolFilter` (whitelist),
+     * `enabledToolNames` (merged into the whitelist, as its docs always
+     * promised), `excludeTools` (denylist, applied after the whitelist), and
+     * the instance-level `tools` config (enabled/include/exclude, `*` globs) —
+     * then applied by `applyToolGate()`. This is the single filter semantics
+     * for every generate/stream path.
      */
+    getToolPolicy(options) {
+        return resolveToolPolicy({
+            options: {
+                toolFilter: options.toolFilter,
+                excludeTools: options.excludeTools,
+                enabledToolNames: options.enabledToolNames,
+            },
+            instanceConfig: this.neurolink?.getToolsConfig(),
+            builtinToolNames: Object.keys(this.directTools ?? {}),
+        });
+    }
     applyToolFiltering(tools, options) {
-        const hasWhitelist = options.toolFilter && options.toolFilter.length > 0;
-        const hasDenylist = options.excludeTools && options.excludeTools.length > 0;
+        const policy = this.getToolPolicy(options);
         // 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 (hasWhitelist) {
-            const allowSet = new Set(options.toolFilter);
-            const result = {};
-            for (const [name, tool] of Object.entries(filtered)) {
-                if (allowSet.has(name)) {
-                    result[name] = tool;
-                }
-            }
-            filtered = result;
-        }
-        if (hasDenylist) {
-            const denySet = new Set(options.excludeTools);
-            for (const name of Object.keys(filtered)) {
-                if (denySet.has(name)) {
-                    delete filtered[name];
-                }
-            }
-        }
+        const filtered = applyToolGate(tools, policy);
         const afterCount = Object.keys(filtered).length;
         if (beforeCount !== afterCount) {
             logger.debug(`Tool filtering applied`, {
                 provider: this.providerName,
                 beforeCount,
                 afterCount,
+                policySources: policy.sources,
                 toolFilter: options.toolFilter,
                 excludeTools: options.excludeTools,
+                enabledToolNames: options.enabledToolNames,
             });
         }
-        // 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,
-                    })),
-                });
+        if (!hasDedupEnabled || dedupConfig === undefined) {
+            return this.sortToolRecord(filtered);
+        }
+        const deduped = this.applyDedupPass(filtered, dedupConfig);
+        // A forced toolChoice must survive dedup: keep-first can collapse the
+        // forced tool into an earlier near-identical signature, and the provider
+        // would then reject the request for naming an unknown tool. Restore it
+        // from the pre-dedup record (whitelisted names are already safe — the
+        // gate runs before dedup, so a whitelist leaves no duplicate to lose to).
+        const forcedName = options.toolChoice?.toolName;
+        if (typeof forcedName === "string" &&
+            !Object.hasOwn(deduped, forcedName) &&
+            Object.hasOwn(filtered, forcedName)) {
+            deduped[forcedName] = filtered[forcedName];
+            logger.debug(`Restored toolChoice-forced tool removed by signature dedup`, { provider: this.providerName, toolName: forcedName });
+        }
+        return this.sortToolRecord(deduped);
+    }
+    /**
+     * Deterministic name-sorted key order. External MCP servers connect and
+     * discover in parallel, so insertion order varies across process restarts;
+     * providers serialize this record in key order (and Anthropic pins its
+     * cache_control breakpoint to the LAST tool), so an unstable order silently
+     * busts provider prompt caches. Runs AFTER the dedup pass — dedup's
+     * keep-first policy must see phase order (built-ins first) so duplicate
+     * winners don't flip when an MCP tool name sorts earlier.
+     */
+    sortToolRecord(tools) {
+        // Null prototype: a tool named "__proto__" must become an own entry, not
+        // a prototype mutation that silently drops the tool.
+        const sorted = Object.create(null);
+        for (const name of Object.keys(tools).sort()) {
+            sorted[name] = tools[name];
+        }
+        return sorted;
+    }
+    /**
+     * On-demand discovery (`tools.discovery: true`): defer external MCP tool
+     * schemas behind one `search_tools` meta-tool. Built-in tools, per-call
+     * tools, explicitly whitelisted tools, and session-pinned (previously
+     * discovered) tools always stay hot. No-op when discovery is off — with a
+     * one-time WARN when the catalog is large enough that selection accuracy
+     * measurably degrades.
+     */
+    async applyToolDiscovery(toolsInput, options) {
+        // Strip a stale meta-tool left by a previous resolution pass (the
+        // stream → generate fallback re-enters resolution with options.tools
+        // already partitioned). Discovery re-partitions against the fresh merged
+        // record below; without this, the collision guard would see our own
+        // meta-tool and skip partitioning, shipping the full catalog AND a stale
+        // search_tools closure. Real user tools named "search_tools" are not
+        // marked and are left untouched.
+        let tools = toolsInput;
+        if (isDiscoveryMetaTool(tools["search_tools"])) {
+            const { search_tools: _stale, ...rest } = tools;
+            tools = rest;
+        }
+        const toolCount = Object.keys(tools).length;
+        const policy = this.getToolPolicy(options);
+        if (!policy.discovery) {
+            if (toolCount > LARGE_CATALOG_WARN_THRESHOLD) {
+                this.warnLargeCatalogOnce(toolCount);
             }
-            return dedupedTools;
+            return tools;
+        }
+        const externalTools = this.neurolink?.getExternalMCPTools() ?? [];
+        if (externalTools.length === 0) {
+            return tools;
+        }
+        // Session pinning requires a caller-provided sessionId. Without one there
+        // is no session identity — pinning to a shared fallback key would leak
+        // one caller's discoveries into every other caller of a shared instance
+        // and monotonically defeat deferral, so pins are simply not persisted.
+        const rawSessionId = options.context?.sessionId;
+        const sessionKey = typeof rawSessionId === "string" && rawSessionId.length > 0
+            ? rawSessionId
+            : typeof rawSessionId === "number"
+                ? String(rawSessionId)
+                : undefined;
+        const pinnedNames = (sessionKey ? this.neurolink?.getDiscoveryPins(sessionKey) : undefined) ??
+            new Set();
+        const perCallNames = new Set(Object.keys(options.tools ?? {}));
+        // Explicitly requested tools stay hot. Allowlist entries may be globs
+        // (e.g. toolFilter: ["github*"]), so match with the same pattern matcher
+        // the gate uses — a Set of pattern STRINGS would defer glob-whitelisted
+        // tools the gate deliberately kept.
+        const explicitPatterns = [
+            ...(options.toolFilter ?? []),
+            ...(options.enabledToolNames ?? []),
+        ];
+        // A toolChoice that forces a named tool must never see that tool
+        // deferred — the provider would reject the request (unknown tool name).
+        const toolChoice = options.toolChoice;
+        if (toolChoice && typeof toolChoice.toolName === "string") {
+            explicitPatterns.push(toolChoice.toolName);
+        }
+        const explicitMatcher = explicitPatterns.length > 0 ? toolNameMatcher(explicitPatterns) : null;
+        const deferrableNames = externalTools
+            .map((t) => t.name)
+            .filter((name) => name in tools &&
+            !perCallNames.has(name) &&
+            !(explicitMatcher ? explicitMatcher(name) : false));
+        return partitionToolsForDiscovery(tools, {
+            deferrableNames,
+            pinnedNames,
+            onHydrate: (names) => {
+                if (sessionKey) {
+                    this.neurolink?.pinDiscoveredTools(sessionKey, names);
+                }
+            },
+        });
+    }
+    static warnedLargeCatalog = false;
+    warnLargeCatalogOnce(toolCount) {
+        if (BaseProvider.warnedLargeCatalog) {
+            return;
+        }
+        BaseProvider.warnedLargeCatalog = true;
+        logger.warn(`[ToolDiscovery] ${toolCount} tools are being sent in full on every request (~${Math.round((toolCount * 175) / 100) / 10}K tokens). Tool-selection accuracy degrades past 30-50 tools — consider enabling on-demand discovery: new NeuroLink({ tools: { discovery: true } })`, { toolCount, provider: this.providerName });
+    }
+    /**
+     * 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.
+     */
+    applyDedupPass(filtered, dedupConfig) {
+        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 filtered;
+        return dedupedTools;
     }
     /**
      * Prepare generation context including tools and model
@@ -613,6 +732,8 @@ export class BaseProvider {
             : {};
         // Apply per-call tool filtering (whitelist/blacklist)
         tools = this.applyToolFiltering(tools, options);
+        // On-demand discovery: defer external MCP schemas behind search_tools
+        tools = await this.applyToolDiscovery(tools, options);
         logger.debug(`Final tools prepared for AI`, {
             provider: this.providerName,
             directTools: getKeyCount(baseTools),
@@ -644,6 +765,8 @@ export class BaseProvider {
         let merged = { ...baseTools, ...externalTools };
         // Apply per-call tool filtering (whitelist/blacklist)
         merged = this.applyToolFiltering(merged, options);
+        // On-demand discovery: defer external MCP schemas behind search_tools
+        merged = await this.applyToolDiscovery(merged, options);
         logger.debug(`Tools prepared for streaming`, {
             provider: this.providerName,
             baseToolCount: Object.keys(baseTools).length,