@juspay/neurolink 9.73.0 → 9.75.0

package/dist/cli/factories/commandFactory.js

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

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

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

package/dist/cli/utils/toolRoutingFlags.js

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

package/dist/core/toolRouting.js

@@ -154,20 +154,48 @@ function parseRouterJson(rawText) {
         throw new Error("Router response is not valid JSON");
     }
 }
+/**
+ * Safely calls the emitDecision callback, swallowing any error so telemetry
+ * can never interfere with the routing result or the caller's turn.
+ */
+function safeEmitDecision(emitDecision, decision) {
+    if (!emitDecision) {
+        return;
+    }
+    try {
+        emitDecision(decision);
+    }
+    catch {
+        // Intentionally swallowed — telemetry must never affect routing behaviour.
+    }
+}
 /**
  * Resolves which registered tool names to EXCLUDE for a single stream() turn.
  * Returns an empty list on any skip/failure path — see module doc.
  */
 export async function resolveToolRoutingExclusions(params) {
-    const { catalog, alwaysIncludeServerIds, userQuery, routerPromptPrefix, routerModel, timeoutMs, generateFn, } = params;
+    const { catalog, alwaysIncludeServerIds, userQuery, routerPromptPrefix, routerModel, timeoutMs, generateFn, emitDecision, } = params;
     const routableServers = catalog.filter((server) => !alwaysIncludeServerIds.includes(server.id));
     const routingStartTime = Date.now();
     try {
         if (!userQuery || routableServers.length <= 1) {
+            const outcome = !userQuery
+                ? "skipped-no-query"
+                : "skipped-single-server";
             logger.debug("[ToolRouting] Routing skipped", {
                 reason: !userQuery ? "missingUserQuery" : "singleRoutableServer",
                 routableServerCount: routableServers.length,
             });
+            safeEmitDecision(emitDecision, {
+                outcome,
+                selectedServerIds: [],
+                excludedServerIds: [],
+                hallucinatedIds: [],
+                excludedToolCount: 0,
+                routableServerCount: routableServers.length,
+                cacheHit: false,
+                durationMs: Date.now() - routingStartTime,
+            });
             return [];
         }
         const routerPrompt = buildRouterPrompt(userQuery, routableServers, routerPromptPrefix);
@@ -190,14 +218,37 @@ export async function resolveToolRoutingExclusions(params) {
                 : {}),
         }), timeoutMs, `Tool routing router call exceeded ${timeoutMs}ms`);
         const rawText = generateResult?.content ?? "";
-        const parsed = routerOutputSchema.safeParse(parseRouterJson(rawText));
-        if (!parsed.success) {
+        /** Shared fail-open handler for both JSON parse and schema validation failures. */
+        const failOpenParse = (extra) => {
             logger.warn("[ToolRouting] Router output validation failed, failing open", {
-                validationErrors: parsed.error.issues.map((issue) => issue.message),
                 rawResponse: rawText,
                 durationMs: Date.now() - routingStartTime,
+                ...extra,
+            });
+            safeEmitDecision(emitDecision, {
+                outcome: "failed-open-parse",
+                selectedServerIds: [],
+                excludedServerIds: [],
+                hallucinatedIds: [],
+                excludedToolCount: 0,
+                routableServerCount: routableServers.length,
+                cacheHit: false,
+                durationMs: Date.now() - routingStartTime,
             });
             return [];
+        };
+        let parsed;
+        try {
+            parsed = routerOutputSchema.safeParse(parseRouterJson(rawText));
+        }
+        catch {
+            // parseRouterJson threw (non-JSON response)
+            return failOpenParse();
+        }
+        if (!parsed.success) {
+            return failOpenParse({
+                validationErrors: parsed.error.issues.map((issue) => issue.message),
+            });
         }
         const routableServerIds = new Set(routableServers.map((server) => server.id));
         const validSelectedIds = parsed.data.servers.filter((serverId) => routableServerIds.has(serverId));
@@ -208,6 +259,16 @@ export async function resolveToolRoutingExclusions(params) {
                 hallucinatedIds,
                 durationMs: Date.now() - routingStartTime,
             });
+            safeEmitDecision(emitDecision, {
+                outcome: "empty-pick",
+                selectedServerIds: [],
+                excludedServerIds: routableServers.map((server) => server.id),
+                hallucinatedIds,
+                excludedToolCount: 0,
+                routableServerCount: routableServers.length,
+                cacheHit: false,
+                durationMs: Date.now() - routingStartTime,
+            });
             return [];
         }
         const unselectedRoutableServers = routableServers.filter((server) => !validSelectedIds.includes(server.id));
@@ -220,13 +281,38 @@ export async function resolveToolRoutingExclusions(params) {
             routableServerCount: routableServers.length,
             durationMs: Date.now() - routingStartTime,
         });
+        safeEmitDecision(emitDecision, {
+            outcome: "applied",
+            selectedServerIds: validSelectedIds,
+            excludedServerIds: unselectedRoutableServers.map((server) => server.id),
+            hallucinatedIds,
+            excludedToolCount: excludedToolNames.length,
+            routableServerCount: routableServers.length,
+            cacheHit: false,
+            durationMs: Date.now() - routingStartTime,
+        });
         return excludedToolNames;
     }
     catch (error) {
+        const isTimeout = error instanceof Error &&
+            error.message.includes("Tool routing router call exceeded");
+        const outcome = isTimeout
+            ? "failed-open-timeout"
+            : "failed-open-error";
         logger.warn("[ToolRouting] Routing failed, failing open", {
             error: error instanceof Error ? error.message : String(error),
             durationMs: Date.now() - routingStartTime,
         });
+        safeEmitDecision(emitDecision, {
+            outcome,
+            selectedServerIds: [],
+            excludedServerIds: [],
+            hallucinatedIds: [],
+            excludedToolCount: 0,
+            routableServerCount: routableServers.length,
+            cacheHit: false,
+            durationMs: Date.now() - routingStartTime,
+        });
         return [];
     }
 }

package/dist/core/toolRoutingCache.d.ts

@@ -0,0 +1,64 @@
+/**
+ * LRU+TTL cache for pre-call tool routing decisions, plus session stickiness
+ * tracking to reduce turn-to-turn server flapping.
+ *
+ * The cache is keyed by a caller-supplied string (typically a normalized hash
+ * of sessionId + routing query). On a hit the cached exclusion list is
+ * returned, skipping the router LLM entirely. On a miss the caller resolves
+ * normally, stores the result, and `recordSelection` is called with the
+ * selected server ids so stickiness can suppress their exclusion for the next
+ * N turns.
+ *
+ * All operations are synchronous and pure (no I/O). The clock is injected via
+ * `now` so tests can control time without `Date.now` side effects.
+ */
+import type { ToolRoutingCacheOptions } from "../types/index.js";
+export declare class ToolRoutingCache {
+    private readonly ttlMs;
+    private readonly maxEntries;
+    private readonly stickyTurns;
+    private readonly now;
+    /** Main LRU+TTL store keyed by routing key. */
+    private readonly store;
+    /** Per-session stickiness tracking keyed by session id. */
+    private readonly sticky;
+    /** Monotonic counter for LRU ordering — incremented on each access. */
+    private accessCounter;
+    constructor(opts?: ToolRoutingCacheOptions);
+    /**
+     * Returns the cached routing result for the given key, or `undefined` on a
+     * miss or expiry. Expired entries are deleted on access (lazy eviction).
+     */
+    get(key: string): {
+        excludedToolNames: string[];
+        selectedServerIds: string[];
+    } | undefined;
+    /**
+     * Stores a routing result under the given key. Evicts the least-recently-
+     * used entry when the store is at capacity. Silently no-ops on any error
+     * (caller is responsible for fail-open behaviour).
+     */
+    set(key: string, value: {
+        excludedToolNames: string[];
+        selectedServerIds: string[];
+    }): void;
+    /**
+     * Records the server ids selected by the router for a session so they stay
+     * warm for the next `stickyTurns` turns. Called after a successful
+     * (non-cached) routing resolution.
+     */
+    recordSelection(sessionId: string, serverIds: string[]): void;
+    /**
+     * Returns the server ids that should be kept warm (not excluded) for the
+     * given session due to stickiness. Decrements the turn counter; when it
+     * reaches zero the entry is removed. Returns an empty array when there is no
+     * active sticky state for the session.
+     */
+    getStickyServerIds(sessionId: string): string[];
+    /**
+     * Scans the store for the entry with the lowest accessOrder and removes it.
+     * O(n) scan is acceptable at the default maxEntries (256); very large caches
+     * should consider an O(1) doubly-linked-list approach instead.
+     */
+    private evictLRU;
+}

package/dist/core/toolRoutingCache.js

@@ -0,0 +1,154 @@
+/**
+ * LRU+TTL cache for pre-call tool routing decisions, plus session stickiness
+ * tracking to reduce turn-to-turn server flapping.
+ *
+ * The cache is keyed by a caller-supplied string (typically a normalized hash
+ * of sessionId + routing query). On a hit the cached exclusion list is
+ * returned, skipping the router LLM entirely. On a miss the caller resolves
+ * normally, stores the result, and `recordSelection` is called with the
+ * selected server ids so stickiness can suppress their exclusion for the next
+ * N turns.
+ *
+ * All operations are synchronous and pure (no I/O). The clock is injected via
+ * `now` so tests can control time without `Date.now` side effects.
+ */
+const DEFAULT_TTL_MS = 60_000;
+const DEFAULT_MAX_ENTRIES = 256;
+const DEFAULT_STICKY_TURNS = 3;
+/**
+ * Internal cap on the number of sessions tracked in the sticky map.
+ * Not configurable via public API — avoids unbounded memory growth when many
+ * ephemeral session ids are generated. Oldest entry (Map insertion order) is
+ * evicted when the cap is reached.
+ */
+const MAX_STICKY_ENTRIES = 1024;
+export class ToolRoutingCache {
+    ttlMs;
+    maxEntries;
+    stickyTurns;
+    now;
+    /** Main LRU+TTL store keyed by routing key. */
+    store = new Map();
+    /** Per-session stickiness tracking keyed by session id. */
+    sticky = new Map();
+    /** Monotonic counter for LRU ordering — incremented on each access. */
+    accessCounter = 0;
+    constructor(opts = {}) {
+        // Fall back to defaults for invalid (<=0 or NaN) values so callers cannot
+        // accidentally disable the cache by passing bad config.
+        const validOrDefault = (v, def) => v !== undefined && Number.isFinite(v) && v > 0 ? v : def;
+        this.ttlMs = validOrDefault(opts.ttlMs, DEFAULT_TTL_MS);
+        this.maxEntries = validOrDefault(opts.maxEntries, DEFAULT_MAX_ENTRIES);
+        this.stickyTurns = validOrDefault(opts.stickyTurns, DEFAULT_STICKY_TURNS);
+        this.now = opts.now ?? Date.now;
+    }
+    /**
+     * Returns the cached routing result for the given key, or `undefined` on a
+     * miss or expiry. Expired entries are deleted on access (lazy eviction).
+     */
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry) {
+            return undefined;
+        }
+        if (this.now() >= entry.expiresAt) {
+            this.store.delete(key);
+            return undefined;
+        }
+        // Bump access order for LRU.
+        entry.accessOrder = ++this.accessCounter;
+        // Return shallow copies so callers cannot mutate cached state.
+        return {
+            excludedToolNames: [...entry.excludedToolNames],
+            selectedServerIds: [...entry.selectedServerIds],
+        };
+    }
+    /**
+     * Stores a routing result under the given key. Evicts the least-recently-
+     * used entry when the store is at capacity. Silently no-ops on any error
+     * (caller is responsible for fail-open behaviour).
+     */
+    set(key, value) {
+        try {
+            if (this.store.size >= this.maxEntries && !this.store.has(key)) {
+                this.evictLRU();
+            }
+            // Defensive copies: guard against callers mutating arrays after storing.
+            this.store.set(key, {
+                excludedToolNames: [...value.excludedToolNames],
+                selectedServerIds: [...value.selectedServerIds],
+                expiresAt: this.now() + this.ttlMs,
+                accessOrder: ++this.accessCounter,
+            });
+        }
+        catch {
+            // Silently no-ops on any error — cache writes are non-fatal.
+        }
+    }
+    /**
+     * Records the server ids selected by the router for a session so they stay
+     * warm for the next `stickyTurns` turns. Called after a successful
+     * (non-cached) routing resolution.
+     */
+    recordSelection(sessionId, serverIds) {
+        if (!sessionId || serverIds.length === 0) {
+            return;
+        }
+        // Evict the oldest session when at the internal cap (Map preserves insertion
+        // order, so the first key is always the oldest).
+        if (this.sticky.size >= MAX_STICKY_ENTRIES && !this.sticky.has(sessionId)) {
+            const oldestKey = this.sticky.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.sticky.delete(oldestKey);
+            }
+        }
+        this.sticky.set(sessionId, {
+            serverIds: [...serverIds],
+            turnsRemaining: this.stickyTurns,
+        });
+    }
+    /**
+     * Returns the server ids that should be kept warm (not excluded) for the
+     * given session due to stickiness. Decrements the turn counter; when it
+     * reaches zero the entry is removed. Returns an empty array when there is no
+     * active sticky state for the session.
+     */
+    getStickyServerIds(sessionId) {
+        if (!sessionId) {
+            return [];
+        }
+        const entry = this.sticky.get(sessionId);
+        if (!entry) {
+            return [];
+        }
+        const ids = [...entry.serverIds];
+        if (entry.turnsRemaining <= 1) {
+            this.sticky.delete(sessionId);
+        }
+        else {
+            entry.turnsRemaining -= 1;
+        }
+        return ids;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Scans the store for the entry with the lowest accessOrder and removes it.
+     * O(n) scan is acceptable at the default maxEntries (256); very large caches
+     * should consider an O(1) doubly-linked-list approach instead.
+     */
+    evictLRU() {
+        let lruKey;
+        let lruOrder = Infinity;
+        for (const [key, entry] of this.store) {
+            if (entry.accessOrder < lruOrder) {
+                lruOrder = entry.accessOrder;
+                lruKey = key;
+            }
+        }
+        if (lruKey !== undefined) {
+            this.store.delete(lruKey);
+        }
+    }
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -356,6 +356,10 @@ ToolIntegrationManager, globalToolIntegrationManager, wrapToolWithElicitation, w
 ElicitationProtocolAdapter, globalElicitationProtocol, isElicitationProtocolMessage, protocolMessageToElicitation, elicitationResponseToProtocol, createElicitationRequest, createElicitationResponse, createElicitationCancel, createTextInputRequest, createSelectRequest, createConfirmationRequest, createFormRequest, } from "./mcp/index.js";
 export { logger } from "./utils/logger.js";
 export { getPoolStats } from "./utils/redis.js";
+// Pre-call tool routing cache (ITEM C: LRU+TTL cache + session stickiness)
+export { ToolRoutingCache } from "./core/toolRoutingCache.js";
+// Pre-call tool routing resolver — exported for host integrations and testing
+export { resolveToolRoutingExclusions, buildToolRoutingCatalog, buildRoutingQueryFromHistory, DEFAULT_ROUTER_PROMPT_PREFIX, } from "./core/toolRouting.js";
 // ============================================================================
 // REAL-TIME SERVICES & TELEMETRY - Enterprise Platform Features
 // ============================================================================