@juspay/neurolink 9.89.0 → 9.91.0

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/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/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/adapters/tts/googleTTSHandler.d.ts

@@ -24,6 +24,7 @@ export declare class GoogleTTSHandler implements TTSHandler {
      * before invoking provider handlers, not inside this class.
      */
     readonly maxTextLength: number;
+    private readonly credentialsPath;
     constructor(credentialsPath?: string);
     /**
      * Validate that the provider is properly configured
@@ -31,6 +32,15 @@ export declare class GoogleTTSHandler implements TTSHandler {
      * @returns True if provider can generate TTS
      */
     isConfigured(): boolean;
+    /**
+     * Lazily construct (and cache) the Google Cloud TTS client.
+     *
+     * `@google-cloud/text-to-speech` is an optional dependency: importing it
+     * only happens here, on first actual use, so a handler instance can be
+     * constructed (e.g. during auto-registration at module load) without the
+     * package being installed.
+     */
+    private getClient;
     /**
      * Get available voices for the provider
      *

package/dist/lib/adapters/tts/googleTTSHandler.js

@@ -1,12 +1,3 @@
-/**
- * Google Cloud Text-to-Speech Handler
- *
- * Handler for Google Cloud Text-to-Speech API integration.
- *
- * @module adapters/tts/googleTTSHandler
- * @see https://cloud.google.com/text-to-speech/docs
- */
-import { TextToSpeechClient } from "@google-cloud/text-to-speech";
 import { TTSError, TTS_ERROR_CODES } from "../../utils/ttsProcessor.js";
 import { ErrorCategory, ErrorSeverity } from "../../constants/enums.js";
 import { logger } from "../../utils/logger.js";
@@ -36,11 +27,10 @@ export class GoogleTTSHandler {
      * before invoking provider handlers, not inside this class.
      */
     maxTextLength = GoogleTTSHandler.DEFAULT_MAX_TEXT_LENGTH;
+    credentialsPath;
     constructor(credentialsPath) {
-        const path = credentialsPath ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
-        if (path) {
-            this.client = new TextToSpeechClient({ keyFilename: path });
-        }
+        this.credentialsPath =
+            credentialsPath ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
     }
     /**
      * Validate that the provider is properly configured
@@ -48,7 +38,24 @@ export class GoogleTTSHandler {
      * @returns True if provider can generate TTS
      */
     isConfigured() {
-        return this.client !== null;
+        return this.credentialsPath !== undefined;
+    }
+    /**
+     * Lazily construct (and cache) the Google Cloud TTS client.
+     *
+     * `@google-cloud/text-to-speech` is an optional dependency: importing it
+     * only happens here, on first actual use, so a handler instance can be
+     * constructed (e.g. during auto-registration at module load) without the
+     * package being installed.
+     */
+    async getClient() {
+        if (!this.client) {
+            const { TextToSpeechClient } = await import("@google-cloud/text-to-speech");
+            this.client = new TextToSpeechClient({
+                keyFilename: this.credentialsPath,
+            });
+        }
+        return this.client;
     }
     /**
      * Get available voices for the provider
@@ -60,7 +67,7 @@ export class GoogleTTSHandler {
      * @returns List of available voices
      */
     async getVoices(languageCode) {
-        if (!this.client) {
+        if (!this.isConfigured()) {
             throw new TTSError({
                 code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
                 message: "Google Cloud TTS client not initialized. Set GOOGLE_APPLICATION_CREDENTIALS or pass credentials path.",
@@ -69,6 +76,7 @@ export class GoogleTTSHandler {
                 retriable: false,
             });
         }
+        const client = await this.getClient();
         const span = SpanSerializer.createSpan(SpanType.TTS, "tts.google.listVoices", {
             "tts.operation": "listVoices",
             "tts.provider": "google",
@@ -84,7 +92,7 @@ export class GoogleTTSHandler {
                 return this.voicesCache.voices;
             }
             // Call Google Cloud listVoices API
-            const [response] = await this.client.listVoices(languageCode ? { languageCode } : {});
+            const [response] = await client.listVoices(languageCode ? { languageCode } : {});
             if (!response.voices || response.voices.length === 0) {
                 logger.warn("Google Cloud TTS returned no voices");
                 const endedSpan = SpanSerializer.endSpan(span, SpanStatus.OK);
@@ -149,7 +157,7 @@ export class GoogleTTSHandler {
      * @returns Audio buffer with metadata
      */
     async synthesize(text, options) {
-        if (!this.client) {
+        if (!this.isConfigured()) {
             throw new TTSError({
                 code: TTS_ERROR_CODES.PROVIDER_NOT_CONFIGURED,
                 message: "Google Cloud TTS client not initialized. Set GOOGLE_APPLICATION_CREDENTIALS or pass credentials path.",
@@ -158,6 +166,7 @@ export class GoogleTTSHandler {
                 retriable: false,
             });
         }
+        const client = await this.getClient();
         const voiceId = options.voice ?? "en-US-Neural2-C";
         const span = SpanSerializer.createSpan(SpanType.TTS, "tts.google.synthesize", {
             "tts.operation": "synthesize",
@@ -196,7 +205,7 @@ export class GoogleTTSHandler {
                     volumeGainDb: options.volumeGainDb ?? 0.0,
                 },
             };
-            const [response] = await this.client.synthesizeSpeech(request, {
+            const [response] = await client.synthesizeSpeech(request, {
                 timeout: GoogleTTSHandler.DEFAULT_API_TIMEOUT_MS,
             });
             const audioContent = response.audioContent;

package/dist/lib/agent/directTools.js

@@ -3,7 +3,6 @@ import * as fs from "fs";
 import * as path from "path";
 import { execFile } from "child_process";
 import { logger } from "../utils/logger.js";
-import { VertexAI } from "@google-cloud/vertexai";
 import { CSVProcessor } from "../utils/csvProcessor.js";
 import { shouldEnableBashTool } from "../utils/toolUtils.js";
 import { tool } from "../utils/tool.js";
@@ -604,6 +603,7 @@ export const directAgentTools = {
                     };
                 }
                 const limitedResults = Math.min(Math.max(maxResults, 1), 5);
+                const { VertexAI } = await import("@google-cloud/vertexai");
                 const vertex_ai = new VertexAI({
                     project: hasProjectId,
                     location: projectLocation,

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