@juspay/neurolink 9.89.0 → 9.91.0

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,

package/dist/lib/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/lib/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/lib/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/index.d.ts

@@ -426,7 +426,7 @@ export { AgentExecuteRequestSchema, AlreadyRunningError, AuthenticationError, Au
  * console.log(response.answer);
  * ```
  */
-export { assembleContext, batchRerank, CharacterChunker, ChunkerRegistry, CohereRelevanceScorer, CrossEncoderReranker, CSVLoader, chunkText, createChunker, createContextWindow, createHybridSearch, createRAGPipeline, createVectorQueryTool, executeWithCircuitBreaker, extractMetadata, formatContextWithCitations, GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
+export { assembleContext, batchRerank, CharacterChunker, ChunkerRegistry, CohereRelevanceScorer, CrossEncoderReranker, CSVLoader, chunkText, createChunker, createContextWindow, createHybridSearch, createRAGPipeline, createVectorQueryTool, executeWithCircuitBreaker, extractMetadata, formatContextWithCitations, GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, ChromaVectorStore, PgVectorStore, PineconeVectorStore, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
 export { ContextBuilder } from "./evaluation/contextBuilder.js";
 export { AuthProviderFactory, createAuthProvider, AuthProviderRegistry, AuthError as AuthErrorFactory, AuthErrorCodes, BaseAuthProvider, InMemorySessionStorage, AuthProviderError, createAuthMiddleware as createAuthProviderMiddleware, createRBACMiddleware, createProtectedMiddleware, createExpressAuthMiddleware, createRequestContext, extractToken, AuthMiddlewareError, AuthMiddlewareErrorCodes, UserRateLimiter, MemoryRateLimitStorage, RedisRateLimitStorage, createRateLimitByUserMiddleware, createAuthenticatedRateLimitMiddleware, createRateLimitStorage, SessionManager, MemorySessionStorage, RedisSessionStorage, createSessionStorage, AuthContextHolder, globalAuthContext, getAuthContext, getCurrentUser, getCurrentSession, isAuthenticated, hasRole, hasAnyRole, hasPermission, hasAllPermissions, requireAuth, requireRole, requirePermission, requireUser, runWithAuthContext, createAuthenticatedContext, RequestContext, NEUROLINK_RESOURCE_ID_KEY, NEUROLINK_THREAD_ID_KEY, createAuthValidatorFromProvider, } from "./auth/index.js";
 export { detectAndRedactPII } from "./utils/piiDetector.js";

package/dist/lib/index.js

@@ -683,7 +683,7 @@ extractMetadata, formatContextWithCitations,
 // Graph RAG
 GraphRAG, getAvailableStrategies, getCircuitBreaker, getDefaultChunkerConfig, getRecommendedStrategy, HTMLChunker, HTMLLoader, InMemoryBM25Index, InMemoryVectorStore, JSONChunker as RAGJSONChunker, JSONLoader, LaTeXChunker, LLMMetadataExtractor, linearCombination, loadDocument, loadDocuments, MarkdownChunker, MarkdownLoader, MDocument, PDFLoader, 
 // RAG Integration for generate/stream
-prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
+prepareRAGTool, processDocument, RAGCircuitBreaker, RAGCircuitBreakerManager, RAGPipeline, RAGRetryHandler, RecursiveChunker, ragCircuitBreakerManager, reciprocalRankFusion, rerank, SemanticChunker, ChromaVectorStore, PgVectorStore, PineconeVectorStore, SentenceChunker, simpleRerank, summarizeContext, TextLoader, TokenChunker, WebLoader, } from "./rag/index.js";
 // Legacy RAGAS evaluation classes are now exported from the unified
 // evaluation block above (via ./evaluation/index.js barrel).
 // ContextBuilder is the only class not covered by the barrel export.

package/dist/lib/mcp/toolRegistry.js

@@ -7,6 +7,7 @@ import { registryLogger } from "../utils/logger.js";
 import { randomUUID } from "crypto";
 import { shouldDisableBuiltinTools } from "../utils/toolUtils.js";
 import { directAgentTools } from "../agent/directTools.js";
+import { convertZodToJsonSchema } from "../utils/schemaConversion.js";
 import { detectCategory, createMCPServerInfo } from "../utils/mcpDefaults.js";
 import { FlexibleToolValidator } from "./flexibleToolValidator.js";
 import { ErrorFactory } from "../utils/errorHandling.js";
@@ -57,10 +58,14 @@ export class MCPToolRegistry extends MCPRegistry {
                 continue;
             }
             const toolId = `direct.${toolName}`;
+            // Register the tool's real parameter schema (converted from Zod) instead
+            // of a `{}` placeholder — token-budget accounting and tool listings read
+            // this ToolInfo, and an empty schema makes both under-count reality.
+            const inputSchema = convertZodToJsonSchema(toolDef.inputSchema);
             const toolInfo = {
                 name: toolName,
                 description: toolDef.description || `Direct tool: ${toolName}`,
-                inputSchema: {},
+                inputSchema,
                 serverId: "direct",
                 category: detectCategory({ isBuiltIn: true, serverId: "direct" }),
             };
@@ -98,7 +103,7 @@ export class MCPToolRegistry extends MCPRegistry {
                     }
                 },
                 description: toolDef.description,
-                inputSchema: {},
+                inputSchema,
             });
             registryLogger.debug(`Registered direct tool: ${toolName} as ${toolId}`);
         }

package/dist/lib/neurolink.d.ts

@@ -6,7 +6,7 @@
  * Uses real MCP infrastructure for tool discovery and execution.
  */
 import type { AgentDefinition, AgentNetworkConfig, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk } from "./types/index.js";
-import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig } from "./types/index.js";
+import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -107,6 +107,9 @@ export declare class NeuroLink {
     private toolRoutingCacheInstance?;
     private toolRoutingVectorCache?;
     private toolDedupConfig?;
+    private toolsConfig?;
+    /** Session-scoped pins of tools discovered via search_tools (tools.discovery mode). */
+    private discoveryPins;
     private enableOrchestration;
     private authProvider?;
     private pendingAuthConfig?;
@@ -812,6 +815,11 @@ export declare class NeuroLink {
     /**
      * Apply per-call tool filtering (whitelist/blacklist) to a ToolInfo array.
      * Used to filter the tool list before building the system prompt.
+     *
+     * Resolves the SAME policy as the native gate (`BaseProvider`
+     * `applyToolFiltering`) — per-call options plus the instance-level `tools`
+     * config — so what the model is told about tools never diverges from the
+     * tools it can actually call.
      */
     private applyToolInfoFiltering;
     private createToolAwareSystemPrompt;
@@ -1194,6 +1202,28 @@ export declare class NeuroLink {
      * parameter through the full call stack.
      */
     getToolDedupConfig(): ToolDedupConfig | undefined;
+    /**
+     * Returns the instance-level `tools` config (master switch, include/exclude
+     * lists, discovery mode), or `undefined` when not provided at construction.
+     *
+     * Called by `BaseProvider.applyToolFiltering` so the tool gate composes the
+     * instance policy with per-call options on every generate/stream call.
+     */
+    getToolsConfig(): ToolConfig | undefined;
+    /**
+     * Tools discovered via `search_tools` for a session (`tools.discovery`
+     * mode). Pinned tools are sent in full on every subsequent call of that
+     * session instead of being deferred — discovery cost is paid once.
+     * Reading refreshes the session's recency (LRU), so active conversations
+     * are never the ones evicted at the session cap.
+     */
+    getDiscoveryPins(sessionKey: string): ReadonlySet<string>;
+    /**
+     * Pin discovered tools to a session (called by the `search_tools`
+     * meta-tool on hydration). Append-only within a session; the map is
+     * bounded by evicting the least-recently-used session past 1000 sessions.
+     */
+    pinDiscoveredTools(sessionKey: string, toolNames: string[]): void;
     /**
      * Curator P1-1: synchronous credential health check for a single provider.
      *