@juspay/neurolink 9.77.0 → 9.79.0

package/dist/lib/index.d.ts

@@ -219,6 +219,7 @@ 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 { cosineSimilarity, ToolEmbeddingIndex, selectRelevantToolNames, } from "./core/toolRoutingEmbedding.js";
 export declare function initializeTelemetry(): Promise<boolean>;
 export declare function getTelemetryStatus(): Promise<{
     enabled: boolean;

package/dist/lib/index.js

@@ -362,6 +362,8 @@ export { getPoolStats } from "./utils/redis.js";
 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";
+// Pre-call tool routing — embedding fast-path (ITEM B: L2 semantic retrieval)
+export { cosineSimilarity, ToolEmbeddingIndex, selectRelevantToolNames, } from "./core/toolRoutingEmbedding.js";
 // ============================================================================
 // REAL-TIME SERVICES & TELEMETRY - Enterprise Platform Features
 // ============================================================================

package/dist/lib/neurolink.d.ts

@@ -102,6 +102,7 @@ export declare class NeuroLink {
     private conversationMemoryConfig?;
     private toolRoutingConfig?;
     private toolRoutingCacheInstance?;
+    private toolRoutingVectorCache?;
     private toolDedupConfig?;
     private enableOrchestration;
     private authProvider?;

package/dist/lib/neurolink.js

@@ -340,7 +340,7 @@ export class NeuroLink {
      * @param result - The result of the tool execution (optional)
      * @param error - The error if execution failed (optional)
      */
-    emitToolEndEvent(toolName, startTime, success, result, error) {
+    emitToolEndEvent(toolName, startTime, success, result, error, executionId) {
         // Emit tool end event (NeuroLink format - enhanced with result/error)
         // Serialize error to string for consumer compatibility (event listeners
         // commonly check `typeof event.error === "string"`).
@@ -350,6 +350,7 @@ export class NeuroLink {
             timestamp: Date.now(),
             result,
             error: error ? error.message : undefined,
+            executionId,
         }));
     }
     // Conversation memory support
@@ -363,6 +364,11 @@ export class NeuroLink {
     // Lazy-initialized routing decision cache (ITEM C). Created on first use so
     // instances that don't use routing pay no overhead.
     toolRoutingCacheInstance;
+    // Persisted vector cache for the L2 embedding fast-path (ITEM B). Populated
+    // on the first turn and reused across subsequent turns so tool embedding
+    // vectors are computed once. Cleared when the catalog changes via
+    // setToolRoutingServers() so stale vectors are never reused.
+    toolRoutingVectorCache;
     // Opt-in tool-signature deduplication config.
     toolDedupConfig;
     // Add orchestration property
@@ -5934,7 +5940,11 @@ Current user's request: ${currentInput}`;
             // Require a non-empty sessionId to avoid anonymous sessions sharing a
             // ":query" namespace (cross-session cache leak).
             const cacheKey = cacheEnabled && sessionId ? `${sessionId}:${routingQuery}` : undefined;
+            const routableServerCount = catalog.filter((s) => !(routingConfig.alwaysIncludeServerIds ?? []).includes(s.id)).length;
             // --- ITEM E: build the emitDecision callback ---
+            // Constructed BEFORE the cache-hit check so it is available for all
+            // outcome paths, including cache-hit turns (Finding 4).
+            const routingStartTime = Date.now();
             const emitDecision = (decision) => {
                 try {
                     const activeSpan = trace.getActiveSpan();
@@ -5949,100 +5959,176 @@ Current user's request: ${currentInput}`;
                     activeSpan.setAttribute("tool_routing.excluded_tool_count", decision.excludedToolCount);
                     activeSpan.setAttribute("tool_routing.cache_hit", decision.cacheHit);
                     activeSpan.setAttribute("tool_routing.duration_ms", decision.durationMs);
+                    // Optional L2 / tool-granularity fields (present only when embedding ran).
+                    if (decision.embeddingActivated !== undefined) {
+                        activeSpan.setAttribute("tool_routing.embedding_activated", decision.embeddingActivated);
+                    }
+                    if (decision.candidateToolCount !== undefined) {
+                        activeSpan.setAttribute("tool_routing.candidate_tool_count", decision.candidateToolCount);
+                    }
+                    if (decision.granularity !== undefined) {
+                        activeSpan.setAttribute("tool_routing.granularity", decision.granularity);
+                    }
                 }
                 catch {
                     // Telemetry must never affect routing behaviour.
                 }
             };
-            // Unified hit/miss block: always produces raw (pre-stickiness) exclusions
-            // so stickiness can be applied identically on both paths below.
+            // Check the cache first.
+            if (cacheEnabled && cache && cacheKey !== undefined) {
+                const cached = cache.get(cacheKey);
+                if (cached) {
+                    // Decrement stickiness turn counter even on a cache hit so the window
+                    // advances correctly regardless of whether the LLM router ran
+                    // (Finding 3). Re-apply stickiness to the cached exclusion list so
+                    // the live stickiness window, not the one at write-time, is honoured
+                    // (Finding 2 complement: we stored the pre-stickiness list, so
+                    // re-applying here gives the correct per-turn view).
+                    let cachedExcluded = cached.excludedToolNames;
+                    if (stickinessEnabled && sessionId) {
+                        try {
+                            const stickyIds = cache.getStickyServerIds(sessionId);
+                            if (stickyIds.length > 0) {
+                                cachedExcluded = cachedExcluded.filter((toolName) => !stickyIds.some((id) => toolName.startsWith(`${id}_`)));
+                            }
+                        }
+                        catch {
+                            // Stickiness failure is non-fatal.
+                        }
+                    }
+                    // Notify the emitDecision callback so custom telemetry sinks observe
+                    // every routing outcome, not just non-cached turns (Finding 4).
+                    const cachedSelectedSet = new Set(cached.selectedServerIds);
+                    const cachedExcludedServerIds = catalog
+                        .map((e) => e.id)
+                        .filter((id) => !cachedSelectedSet.has(id));
+                    emitDecision({
+                        outcome: "cache-hit",
+                        selectedServerIds: cached.selectedServerIds,
+                        excludedServerIds: cachedExcludedServerIds,
+                        hallucinatedIds: [],
+                        excludedToolCount: cachedExcluded.length,
+                        routableServerCount,
+                        cacheHit: true,
+                        durationMs: Date.now() - routingStartTime,
+                    });
+                    logger.debug("[ToolRouting] Cache hit, skipping router LLM", {
+                        hasSessionId: !!sessionId,
+                        routingQueryLength: routingQuery.length,
+                    });
+                    if (cachedExcluded.length > 0) {
+                        options.excludeTools = [
+                            ...(options.excludeTools ?? []),
+                            ...cachedExcluded,
+                        ];
+                    }
+                    return;
+                }
+            }
+            // The router call below re-enters the public generate(), whose finally
+            // block resets _disableToolCacheForCurrentRequest to false. That flag is
+            // turn-scoped (set at the top of this turn) and read by the main tool
+            // execution path that runs after routing, so save it before the router
+            // call and restore it afterward to keep the turn's cache setting intact.
+            const cacheDisabledForCurrentRequest = this._disableToolCacheForCurrentRequest;
             let routedExcludeTools;
-            let selectedServerIds = [];
             let resolvedDecision;
-            let fromCache = false;
-            const cached = cacheEnabled && cache && cacheKey !== undefined
-                ? cache.get(cacheKey)
-                : undefined;
-            if (cached) {
-                // Cache HIT — use stored raw exclusions (pre-stickiness).
-                fromCache = true;
-                routedExcludeTools = [...cached.excludedToolNames];
-                selectedServerIds = [...cached.selectedServerIds];
-                logger.debug("[ToolRouting] Cache hit, skipping router LLM", {
-                    cacheKey,
-                });
-                // Emit cache-hit telemetry with full parity to the miss path.
-                try {
-                    const activeSpan = trace.getActiveSpan();
-                    if (activeSpan) {
-                        const routableCount = catalog.filter((s) => !(routingConfig.alwaysIncludeServerIds ?? []).includes(s.id)).length;
-                        activeSpan.setAttribute("tool_routing.outcome", "cache-hit");
-                        activeSpan.setAttribute("tool_routing.routable_server_count", routableCount);
-                        activeSpan.setAttribute("tool_routing.cache_hit", true);
-                        activeSpan.setAttribute("tool_routing.selected_server_ids", spanJsonAttribute(selectedServerIds));
-                        activeSpan.setAttribute("tool_routing.excluded_tool_count", routedExcludeTools.length);
+            try {
+                // Intercept the decision so we can store it in the cache.
+                const captureDecision = (decision) => {
+                    resolvedDecision = decision;
+                    emitDecision(decision);
+                };
+                // --- ITEM B: build the embedFn for the L2 embedding fast-path ---
+                // The vector cache is persisted at the NeuroLink instance level so
+                // tool embedding vectors are computed once and reused across turns
+                // (Finding 1 fix). It is cleared by setToolRoutingServers() when the
+                // catalog changes so stale vectors are never used after an update.
+                let routingEmbedFn;
+                const embeddingCfg = routingConfig.embedding;
+                if (embeddingCfg?.enabled === true) {
+                    try {
+                        // Resolve the embedding provider: use the explicitly configured one
+                        // if present, otherwise fall back to the stream/generate call's
+                        // provider. The factory call is wrapped in try/catch so a provider
+                        // that doesn't support embedMany (it throws at call time, not
+                        // construction time) fails open when routingEmbedFn is invoked.
+                        const embProviderName = embeddingCfg.provider ??
+                            (options.provider && options.provider !== "auto"
+                                ? options.provider
+                                : undefined) ??
+                            routingConfig.routerModel?.provider;
+                        if (embProviderName) {
+                            const embProvider = await AIProviderFactory.createProvider(embProviderName, embeddingCfg.model, true, this, undefined, this.resolveCredentials(options.credentials));
+                            // Bind embedMany with the configured model (may be undefined —
+                            // the provider uses its default embedding model in that case).
+                            routingEmbedFn = (texts) => withTimeout(embProvider.embedMany(texts, embeddingCfg.model), embeddingCfg.timeoutMs ?? 10000);
+                            // Lazy-init the persistent vector cache for this instance.
+                            // Subsequent turns reuse the same Map so text→vector lookups
+                            // already populated from earlier turns are served from memory.
+                            if (!this.toolRoutingVectorCache) {
+                                this.toolRoutingVectorCache = new Map();
+                            }
+                        }
+                    }
+                    catch (embSetupError) {
+                        logger.debug("[ToolRouting] Embedding provider setup failed, L2 path disabled for this turn", {
+                            error: embSetupError instanceof Error
+                                ? embSetupError.message
+                                : String(embSetupError),
+                        });
+                        // routingEmbedFn remains undefined — fast-path is skipped.
                     }
                 }
-                catch {
-                    // Telemetry must never affect routing behaviour.
-                }
+                routedExcludeTools = await resolveToolRoutingExclusions({
+                    catalog,
+                    alwaysIncludeServerIds: routingConfig.alwaysIncludeServerIds ?? [],
+                    userQuery: routingQuery,
+                    routerPromptPrefix: routingConfig.routerPromptPrefix,
+                    routerModel: {
+                        provider: routingConfig.routerModel?.provider ??
+                            options.provider,
+                        model: routingConfig.routerModel?.model ?? options.model,
+                        region: routingConfig.routerModel?.region ?? options.region,
+                        temperature: routingConfig.routerModel?.temperature,
+                    },
+                    timeoutMs: routingConfig.timeoutMs ?? DEFAULT_TOOL_ROUTING_TIMEOUT_MS,
+                    // Forward the abort signal so a cancelled turn aborts the router
+                    // call promptly instead of waiting out the routing timeout.
+                    generateFn: (generateOptions) => this.generate({
+                        ...generateOptions,
+                        abortSignal: options.abortSignal,
+                    }),
+                    emitDecision: captureDecision,
+                    // L2 / ITEM D — only populated when embedding is configured.
+                    embedFn: routingEmbedFn,
+                    embeddingConfig: embeddingCfg,
+                    granularity: routingConfig.granularity ?? "server",
+                    // Pass the persistent vector cache so tool embeddings are reused
+                    // across turns (Finding 1).
+                    embeddingVectorCache: routingEmbedFn !== undefined
+                        ? this.toolRoutingVectorCache
+                        : undefined,
+                });
             }
-            else {
-                // Cache MISS — run the router LLM.
-                // The router call re-enters the public generate(), whose finally block
-                // resets _disableToolCacheForCurrentRequest to false. That flag is
-                // turn-scoped and read by the main tool execution path after routing, so
-                // save it before the router call and restore it afterward.
-                const cacheDisabledForCurrentRequest = this._disableToolCacheForCurrentRequest;
-                try {
-                    // Intercept the decision so we can store it in the cache.
-                    const captureDecision = (decision) => {
-                        resolvedDecision = decision;
-                        emitDecision(decision);
-                    };
-                    routedExcludeTools = await resolveToolRoutingExclusions({
-                        catalog,
-                        alwaysIncludeServerIds: routingConfig.alwaysIncludeServerIds ?? [],
-                        userQuery: routingQuery,
-                        routerPromptPrefix: routingConfig.routerPromptPrefix,
-                        routerModel: {
-                            provider: routingConfig.routerModel?.provider ??
-                                options.provider,
-                            model: routingConfig.routerModel?.model ?? options.model,
-                            region: routingConfig.routerModel?.region ?? options.region,
-                            temperature: routingConfig.routerModel?.temperature,
-                        },
-                        timeoutMs: routingConfig.timeoutMs ?? DEFAULT_TOOL_ROUTING_TIMEOUT_MS,
-                        // Forward the abort signal so a cancelled turn aborts the router
-                        // call promptly instead of waiting out the routing timeout.
-                        generateFn: (generateOptions) => this.generate({
-                            ...generateOptions,
-                            abortSignal: options.abortSignal,
-                        }),
-                        emitDecision: captureDecision,
-                    });
-                }
-                finally {
-                    this._disableToolCacheForCurrentRequest =
-                        cacheDisabledForCurrentRequest;
-                }
-                if (resolvedDecision?.outcome === "applied") {
-                    selectedServerIds = resolvedDecision.selectedServerIds;
-                }
+            finally {
+                this._disableToolCacheForCurrentRequest =
+                    cacheDisabledForCurrentRequest;
             }
             // Aborted during the router call — skip applying now-stale exclusions;
             // the main generation path enforces the abort itself.
             if (options.abortSignal?.aborted) {
                 return;
             }
-            // Capture raw (pre-stickiness) exclusions for cache storage on MISS path.
-            const rawExclusions = [...routedExcludeTools];
-            // Apply stickiness on BOTH hit and miss paths: the sticky ids were
-            // recorded on a prior turn and represent servers that should stay warm for
-            // the current turn. Consuming (decrementing) them before recordSelection
-            // ensures the window covers the correct set of future turns rather than
-            // burning one count on the same turn the selection is recorded
-            // (off-by-one fix).
+            // Snapshot the raw (pre-stickiness) exclusion list before applying
+            // stickiness overrides. The cache stores this snapshot so future cache
+            // hits can re-apply the then-current stickiness state (Finding 2).
+            const preStickinessExcludeTools = routedExcludeTools;
+            // Apply stickiness FIRST: the sticky ids were recorded on a prior turn and
+            // represent servers that should stay warm for the current turn. Consuming
+            // (decrementing) them before recordSelection ensures the window covers the
+            // correct set of future turns rather than burning one count on the same
+            // turn the selection is recorded (off-by-one fix).
             if (stickinessEnabled && cache && sessionId) {
                 try {
                     const stickyIds = cache.getStickyServerIds(sessionId);
@@ -6057,15 +6143,16 @@ Current user's request: ${currentInput}`;
                     // Stickiness failure is non-fatal.
                 }
             }
-            // --- ITEM C: store result for future turns (MISS path only) ---
-            // Cache stores RAW (pre-stickiness) exclusions so the cached value is
-            // correct regardless of which sessions hit it on subsequent turns.
-            if (!fromCache && resolvedDecision?.outcome === "applied" && cache) {
+            // --- ITEM C: store result for future turns ---
+            if (resolvedDecision?.outcome === "applied" && cache) {
+                // Store the PRE-stickiness exclusion list in the cache so future hits
+                // re-apply the live stickiness window rather than the one from this
+                // turn (Finding 2).
                 if (cacheEnabled && cacheKey !== undefined) {
                     try {
                         cache.set(cacheKey, {
-                            excludedToolNames: rawExclusions,
-                            selectedServerIds,
+                            excludedToolNames: preStickinessExcludeTools,
+                            selectedServerIds: resolvedDecision.selectedServerIds,
                         });
                     }
                     catch {
@@ -6077,7 +6164,7 @@ Current user's request: ${currentInput}`;
                 // the same turn it is set (the off-by-one fix above).
                 if (stickinessEnabled && sessionId) {
                     try {
-                        cache.recordSelection(sessionId, selectedServerIds);
+                        cache.recordSelection(sessionId, resolvedDecision.selectedServerIds);
                     }
                     catch {
                         // Stickiness failure is non-fatal.
@@ -6174,6 +6261,12 @@ Current user's request: ${currentInput}`;
             return;
         }
         this.toolRoutingConfig.servers = servers;
+        // Clear the persisted vector cache so tool vectors are recomputed against
+        // the new catalog on the next turn (stale vectors must never be reused).
+        this.toolRoutingVectorCache = undefined;
+        // Cached routing decisions are catalog-dependent too; force the next turn
+        // to recompute exclusions against the new server/tool set.
+        this.toolRoutingCacheInstance = undefined;
     }
     async validateStreamRequestOptions(options, startTime) {
         await this.validateStreamInput(options);
@@ -8484,9 +8577,16 @@ Current user's request: ${currentInput}`;
             : params
                 ? JSON.stringify(params)
                 : "";
+        const executionStartTime = Date.now();
+        // Per-invocation id so consumers can correlate a tool:start with its matching
+        // tool:end even when the same tool runs multiple times concurrently.
+        const executionId = `${toolName}-${executionStartTime}-${Math.random()
+            .toString(36)
+            .slice(2, 11)}`;
         return {
             functionTag: "NeuroLink.executeTool",
-            executionStartTime: Date.now(),
+            executionStartTime,
+            executionId,
             externalTool,
             toolType,
             inputSize: inputStr.length,
@@ -8544,6 +8644,7 @@ Current user's request: ${currentInput}`;
         this.emitter.emit("tool:start", createToolEventPayload(toolName, {
             timestamp: executionContext.executionStartTime,
             input: params,
+            executionId: executionContext.executionId,
         }));
         const toolInfo = this.toolRegistry.getToolInfo(toolName);
         const finalOptions = {
@@ -8709,7 +8810,7 @@ Current user's request: ${currentInput}`;
             prepared.metrics.errorCategories[mappedCategory] =
                 (prepared.metrics.errorCategories[mappedCategory] || 0) + 1;
         }
-        this.emitToolEndEvent(toolName, executionContext.executionStartTime, !isToolError, result, isToolError && errorText ? new Error(errorText) : undefined);
+        this.emitToolEndEvent(toolName, executionContext.executionStartTime, !isToolError, result, isToolError && errorText ? new Error(errorText) : undefined, executionContext.executionId);
         toolSpan.setAttribute("tool.result.status", isToolError ? "error" : "success");
         toolSpan.setAttribute("tool.duration_ms", executionTime);
         return result;
@@ -8728,7 +8829,7 @@ Current user's request: ${currentInput}`;
             });
             prepared.metrics.errorCategories[ErrorCategory.EXECUTION] =
                 (prepared.metrics.errorCategories[ErrorCategory.EXECUTION] || 0) + 1;
-            this.emitToolEndEvent(toolName, executionContext.executionStartTime, false, undefined, new Error(`Circuit breaker open for ${toolName} (state=${error.breakerState}, failures=${error.failureCount})`));
+            this.emitToolEndEvent(toolName, executionContext.executionStartTime, false, undefined, new Error(`Circuit breaker open for ${toolName} (state=${error.breakerState}, failures=${error.failureCount})`), executionContext.executionId);
             toolSpan.setAttribute("tool.result.status", "circuit_breaker_open");
             toolSpan.setAttribute("tool.duration_ms", executionTime);
             toolSpan.setAttribute("tool.circuit_breaker.state", error.breakerState);
@@ -8783,7 +8884,7 @@ Current user's request: ${currentInput}`;
         const category = structuredError.category || ErrorCategory.EXECUTION;
         prepared.metrics.errorCategories[category] =
             (prepared.metrics.errorCategories[category] || 0) + 1;
-        this.emitToolEndEvent(toolName, executionContext.executionStartTime, false, undefined, structuredError);
+        this.emitToolEndEvent(toolName, executionContext.executionStartTime, false, undefined, structuredError, executionContext.executionId);
         // Gate on listenerCount: Node EventEmitter rethrows the original error
         // from emit("error", e) when no listener is registered, which would
         // short-circuit the surrounding flow and surface as an unhandled

package/dist/lib/tasks/autoresearchTaskExecutor.js

@@ -220,7 +220,7 @@ export async function executeAutoresearchTick(task, neurolink, emitter) {
             ...(phasePolicy.forcedTool
                 ? {
                     prepareStep: ({ stepNumber }) => {
-                        if (stepNumber === 0) {
+                        if (stepNumber === 0 && phasePolicy.forcedTool) {
                             return {
                                 toolChoice: {
                                     type: "tool",

package/dist/lib/types/toolRouting.d.ts

@@ -38,6 +38,71 @@ export type ToolRoutingModelConfig = {
     /** Router sampling temperature. Default: 0. */
     temperature?: number;
 };
+/**
+ * Weights for the hybrid scoring formula used by `ToolEmbeddingIndex.rank()`.
+ * Scores are computed as: `cosine * cosine + bm25 * bm25Score` then
+ * normalized before sorting.
+ * Default: `{ cosine: 0.8, bm25: 0.2 }`.
+ */
+export type ToolRetrievalWeights = {
+    /** Weight applied to the cosine-similarity (dense) component. */
+    cosine: number;
+    /** Weight applied to the BM25 (sparse/lexical) component. */
+    bm25: number;
+};
+/**
+ * Configuration for the L2 embedding fast-path (ITEM B).
+ *
+ * When enabled and the catalog's total tool count reaches `minToolsToActivate`,
+ * a hybrid cosine + BM25 retriever ranks all tools by relevance to the query
+ * and takes the top-`topK` candidates. This is far cheaper than an LLM call
+ * (sub-10 ms warm) and fires BEFORE or INSTEAD of the LLM router.
+ *
+ * Fail-open: any embedding error (missing provider, network failure, wrong
+ * model) silently falls back to the existing LLM-router / server-granularity
+ * path — the turn is never broken.
+ */
+export type ToolRoutingEmbeddingConfig = {
+    /**
+     * Activate the embedding fast-path. Default: false (backward-compatible).
+     * Setting this to true without supplying `provider`/`model` causes the SDK
+     * to try the stream call's configured provider; if that provider does not
+     * support embeddings the layer fails open.
+     */
+    enabled?: boolean;
+    /**
+     * Maximum number of top-ranked tool candidates passed to the post-embedding
+     * decision stage. Default: 20.
+     */
+    topK?: number;
+    /**
+     * Minimum total tool count in the catalog before the embedding path
+     * activates. Below this threshold the catalog is small enough that the LLM
+     * router alone is cheap and fast. Default: 20.
+     */
+    minToolsToActivate?: number;
+    /**
+     * Weights for the hybrid scoring formula:
+     *   score = cosine * cosineSim + bm25 * bm25Score  (both normalized to [0,1])
+     * Default: `{ cosine: 0.8, bm25: 0.2 }`.
+     */
+    weights?: ToolRetrievalWeights;
+    /**
+     * Provider name to use for the embedding call (e.g. "openai", "vertex").
+     * Defaults to the stream/generate call's configured provider. The provider
+     * must support `embedMany()`.
+     */
+    provider?: string;
+    /**
+     * Embedding model name (provider-specific). When omitted the provider's
+     * default embedding model is used (e.g. text-embedding-3-small for OpenAI).
+     */
+    model?: string;
+    /**
+     * Timeout for embedding calls in milliseconds. Default: 10000.
+     */
+    timeoutMs?: number;
+};
 /** Constructor-level configuration for pre-call tool routing. */
 export type ToolRoutingConfig = {
     /** Master switch. Routing runs only when true AND the server catalog is non-empty. */
@@ -88,6 +153,24 @@ export type ToolRoutingConfig = {
         /** Number of turns for which a previously-selected server stays warm. Default: 3. */
         turns?: number;
     };
+    /**
+     * L2 embedding fast-path (ITEM B). When enabled the SDK ranks tools by
+     * semantic + lexical relevance using a hybrid cosine/BM25 score and narrows
+     * the candidate set BEFORE (or instead of) the LLM router. Disabled by
+     * default for backward compatibility.
+     */
+    embedding?: ToolRoutingEmbeddingConfig;
+    /**
+     * Routing granularity (ITEM D).
+     *
+     * - `"server"` (default) — routing excludes the tools of entire unpicked
+     *   servers. This is the original behavior.
+     * - `"tool"` — routing excludes individual tools that are not in the
+     *   embedding top-K candidate set, regardless of which server they belong
+     *   to. Requires `embedding.enabled: true`; if the embedding fast-path is
+     *   off (or fails) the granularity falls back to `"server"` automatically.
+     */
+    granularity?: "server" | "tool";
 };
 /** Catalog entry pairing a server descriptor with its registered tool names. */
 export type ToolRoutingCatalogEntry = {
@@ -152,6 +235,19 @@ export type ToolRoutingDecision = {
     cacheHit: boolean;
     /** Wall-clock time spent in the routing resolution in milliseconds. */
     durationMs: number;
+    /** True when the L2 embedding fast-path ran and produced candidate results. */
+    embeddingActivated?: boolean;
+    /**
+     * Number of tool candidates produced by the embedding retriever before the
+     * post-embedding server or tool filtering step.
+     */
+    candidateToolCount?: number;
+    /**
+     * Granularity at which exclusions were applied ("server" or "tool").
+     * Matches `ToolRoutingConfig.granularity`; present only when routing was
+     * applied (outcome === "applied").
+     */
+    granularity?: "server" | "tool";
 };
 /** Parameters for `resolveToolRoutingExclusions()`. */
 export type ToolRoutingResolutionParams = {
@@ -176,4 +272,79 @@ export type ToolRoutingResolutionParams = {
      * the resolver.
      */
     emitDecision?: (decision: ToolRoutingDecision) => void;
+    /**
+     * Injected async function that converts an array of texts into embedding
+     * vectors. Built by the caller (NeuroLink) from the configured embedding
+     * provider so the resolver stays pure and free of provider imports.
+     * When undefined the embedding fast-path is skipped entirely.
+     */
+    embedFn?: (texts: string[]) => Promise<number[][]>;
+    /**
+     * Embedding fast-path configuration forwarded from `ToolRoutingConfig`.
+     * Only consulted when `embedFn` is provided.
+     */
+    embeddingConfig?: ToolRoutingEmbeddingConfig;
+    /**
+     * Routing granularity forwarded from `ToolRoutingConfig`. Default: "server".
+     */
+    granularity?: "server" | "tool";
+    /**
+     * Optional shared vector cache for the L2 embedding fast-path. When
+     * supplied, tool embedding vectors computed on prior turns are reused rather
+     * than re-fetched from the embedding provider on every call.
+     *
+     * The NeuroLink instance manages the lifecycle: it creates the Map once and
+     * passes the same reference across turns. It clears the reference when the
+     * tool catalog changes (via `setToolRoutingServers`) so stale vectors are
+     * never used after a catalog update.
+     */
+    embeddingVectorCache?: Map<string, number[]>;
+};
+/**
+ * A single item in the tool retrieval catalog, pairing a tool name with the
+ * text (tool description + server context) used to build its embedding vector.
+ */
+export type ToolRetrievalItem = {
+    /** Fully-qualified tool name (e.g. `${serverId}_${toolName}`). */
+    name: string;
+    /** Descriptive text used as the embedding document for this tool. */
+    text: string;
+};
+/**
+ * One ranked result from `ToolEmbeddingIndex.rank()` or
+ * `selectRelevantToolNames()`.
+ */
+export type ToolRetrievalRankedResult = {
+    /** Tool name (mirrors `ToolRetrievalItem.name`). */
+    name: string;
+    /** Combined hybrid score (higher = more relevant). */
+    score: number;
+};
+/**
+ * Options passed to `selectRelevantToolNames()` — the high-level convenience
+ * wrapper around `ToolEmbeddingIndex`.
+ */
+export type ToolRetrievalSelectOptions = {
+    /** Maximum number of tool names to return. */
+    topK: number;
+    /** Optional weight override (defaults to `{ cosine: 0.8, bm25: 0.2 }`). */
+    weights?: ToolRetrievalWeights;
+    /**
+     * Async function that converts an array of text strings into embedding
+     * vectors. Must return one vector per input text in the same order.
+     * Errors thrown here propagate to the caller (so it can fail open).
+     */
+    embedFn: (texts: string[]) => Promise<number[][]>;
+    /**
+     * Optional shared vector cache (keyed by text string). When supplied the
+     * underlying `ToolEmbeddingIndex` reads from and writes to this Map so that
+     * tool vectors computed on a prior call are reused on subsequent calls for
+     * the same item text. Callers that want warm-cache behavior across turns
+     * should pass the same Map instance each time.
+     */
+    vectorCache?: Map<string, number[]>;
+    /**
+     * Timeout for each embedding provider call in milliseconds. Default: 10000.
+     */
+    timeoutMs?: number;
 };

package/dist/lib/workflow/core/ensembleExecutor.js

@@ -128,7 +128,6 @@ async function executeModel(options, workflowDefaultSystemPrompt) {
         let result;
         let attempts = 0;
         const MAX_ATTEMPTS = 2;
-        /* eslint-disable no-constant-condition */
         while (true) {
             attempts++;
             result = await executeWithTimeout(async () => {
@@ -145,7 +144,6 @@ async function executeModel(options, workflowDefaultSystemPrompt) {
             }
             logger.warn(`[${functionTag}] Model returned empty content — retrying once`, { provider: model.provider, model: model.model, attempt: attempts });
         }
-        /* eslint-enable no-constant-condition */
         const responseTime = Date.now() - startTime;
         logger.debug(`[${functionTag}] Model execution successful`, {
             provider: model.provider,

package/dist/neurolink.d.ts

@@ -102,6 +102,7 @@ export declare class NeuroLink {
     private conversationMemoryConfig?;
     private toolRoutingConfig?;
     private toolRoutingCacheInstance?;
+    private toolRoutingVectorCache?;
     private toolDedupConfig?;
     private enableOrchestration;
     private authProvider?;