@juspay/neurolink 9.79.3 → 9.80.1

package/dist/neurolink.js

@@ -87,6 +87,7 @@ import { isNonNullObject } from "./utils/typeUtils.js";
 import { getWorkflow } from "./workflow/core/workflowRegistry.js";
 import { runWorkflow } from "./workflow/core/workflowRunner.js";
 import { ModelPool, classifyProviderError } from "./routing/index.js";
+import { ClassifierRouter } from "./routing/classifierRouter.js";
 import { looksLikeModelAccessDenied as sharedLooksLikeModelAccessDenied, isNonRetryableProviderError as sharedIsNonRetryableProviderError, } from "./utils/providerErrorClassification.js";
 /**
  * NL-002: Classify MCP error messages into categories for AI disambiguation.
@@ -388,6 +389,9 @@ export class NeuroLink {
     // RequestRouter: pluggable pre-call provider/model selector.
     // Stored directly from config.requestRouter; null when not configured.
     requestRouter;
+    // ClassifierRouter: opt-in "classify → pick model + tools" pre-call router.
+    // Built from config.classifierRouter; null when not configured.
+    classifierRouter;
     /**
      * Merge instance-level credentials with per-call credentials.
      *
@@ -796,6 +800,17 @@ export class NeuroLink {
         this.modelPool = config?.modelPool ? new ModelPool(config.modelPool) : null;
         // RequestRouter: store the host-supplied function; null when not configured.
         this.requestRouter = config?.requestRouter ?? null;
+        // ClassifierRouter: opt-in. The LLM strategy reuses this instance's
+        // generate() (marked so it never recursively re-routes). Fails open.
+        this.classifierRouter = config?.classifierRouter?.enabled
+            ? new ClassifierRouter(config.classifierRouter, {
+                generate: (genOptions) => this.generate(genOptions),
+                logger: {
+                    debug: (message, meta) => logger.debug(message, meta),
+                    warn: (message, meta) => logger.warn(message, meta),
+                },
+            })
+            : null;
         logger.setEventEmitter(this.emitter);
         // Read tool cache duration from environment variables, with a default
         const cacheDurationEnv = process.env.NEUROLINK_TOOL_CACHE_DURATION;
@@ -3105,6 +3120,13 @@ Current user's request: ${currentInput}`;
     }
     async runStandardGenerateRequest(options, originalPrompt, generateSpan) {
         const startTime = Date.now();
+        // Pre-call classifier router: opt-in. Classifies the request and selects a
+        // provider/model from the configured base pool (and optionally narrows the
+        // tool set) BEFORE orchestration/requestRouter, so it takes precedence.
+        // Fails open.
+        await this.applyClassifierRouting(options, options.input?.text ?? originalPrompt ?? "", !options.disableTools &&
+            (!!(options.tools && Object.keys(options.tools).length > 0) ||
+                this.getCustomTools().size > 0), !!(options.input?.images && options.input.images.length > 0), options.thinkingConfig?.thinkingLevel);
         await this.maybeApplyGenerateOrchestration(options);
         // Pre-call request router: opt-in, only when the caller did not set both
         // provider+model. Fails open (any router error leaves options unchanged).
@@ -3241,6 +3263,12 @@ Current user's request: ${currentInput}`;
         if (!this.requestRouter) {
             return;
         }
+        // Stand down if the classifier router already selected a provider/model on
+        // this turn — one explicit precedence order: classifierRouter wins.
+        if (options.context
+            ?.__classifierRouted) {
+            return;
+        }
         // Skip if the caller explicitly set both provider AND model — they know
         // what they want; the router should not override an intentional choice.
         if (options.provider && options.model) {
@@ -3307,6 +3335,103 @@ Current user's request: ${currentInput}`;
             });
         }
     }
+    /**
+     * Applies the host-configured `classifierRouter` to `options` in place.
+     *
+     * Classifies the request by difficulty and selects a provider/model from the
+     * configured base pool (cheaper/faster for easy tasks, more capable for hard
+     * ones), and optionally narrows the tool set via `toolFilter`/`excludeTools`.
+     *
+     * Skipped when: no router is configured; the inbound call is the classifier's
+     * own generate() (marked `__classifierRouted`); the caller pinned BOTH
+     * provider and model; or a ModelPool is configured (the pool owns selection).
+     * Fails open — any error leaves options unchanged.
+     */
+    async applyClassifierRouting(options, promptText, hasTools, requiresVision, thinkingLevel) {
+        if (!this.classifierRouter) {
+            return;
+        }
+        const opt = options;
+        // Prevent recursion: the LLM classifier itself calls generate() with this
+        // marker set. Also respect any explicit prior routing decision.
+        if (opt.context?.__classifierRouted) {
+            return;
+        }
+        // Honor an intentional caller choice of BOTH provider and model.
+        if (options.provider && options.model) {
+            return;
+        }
+        // A ModelPool overrides provider/model per member unconditionally; let it
+        // own selection (mirrors applyRequestRouter precedence).
+        if (this.modelPool) {
+            logger.debug("[NeuroLink] applyClassifierRouting: skipped — modelPool takes precedence");
+            return;
+        }
+        const sessionId = typeof opt.context?.sessionId === "string"
+            ? opt.context.sessionId
+            : undefined;
+        try {
+            const decision = await this.classifierRouter.route({
+                prompt: promptText,
+                estimatedInputTokens: Math.ceil((promptText?.length ?? 0) / 4),
+                hasTools,
+                requiresVision,
+                thinkingLevel,
+                sessionId,
+            });
+            if (!decision) {
+                return;
+            }
+            // Apply provider/model/region as a coherent set (same discipline as
+            // applyRequestRouter): only fill fields the caller did not pin.
+            if (decision.provider && !options.provider) {
+                options.provider = decision.provider;
+                if (decision.model && !options.model) {
+                    options.model = decision.model;
+                }
+                if (decision.region && !options.region) {
+                    options.region = decision.region;
+                }
+            }
+            else if (!decision.provider && decision.model && !options.model) {
+                options.model = decision.model;
+            }
+            // Narrow tools unless the caller disabled tools entirely.
+            if (!opt.disableTools) {
+                if (decision.excludeTools && decision.excludeTools.length > 0) {
+                    opt.excludeTools = Array.from(new Set([...(opt.excludeTools ?? []), ...decision.excludeTools]));
+                }
+                if (decision.toolFilter && decision.toolFilter.length > 0) {
+                    const allow = decision.toolFilter;
+                    opt.toolFilter =
+                        opt.toolFilter && opt.toolFilter.length > 0
+                            ? opt.toolFilter.filter((t) => allow.includes(t))
+                            : [...allow];
+                }
+            }
+            // Mark routed so orchestration/requestRouter stand down this turn.
+            if (decision.provider || decision.model) {
+                const ctx = opt.context ?? {};
+                ctx.__classifierRouted = true;
+                opt.context = ctx;
+            }
+            if (decision.reason) {
+                logger.debug("[NeuroLink] classifierRouter decision", {
+                    reason: decision.reason,
+                    difficulty: decision.difficulty,
+                    provider: options.provider,
+                    model: options.model,
+                });
+            }
+        }
+        catch (classifierErr) {
+            logger.warn("[NeuroLink] classifierRouter threw — proceeding unrouted", {
+                error: classifierErr instanceof Error
+                    ? classifierErr.message
+                    : String(classifierErr),
+            });
+        }
+    }
     async prepareGenerateAugmentations(options) {
         if (options.rag?.files?.length) {
             try {
@@ -5829,6 +5954,12 @@ Current user's request: ${currentInput}`;
             // classify correctly. After the workflow short-circuit, so workflow
             // streams skip it.
             await context.with(streamSpanContext, () => this.setLangfuseContextFromOptions(options, () => this.applyToolRoutingExclusions(options, originalPrompt)));
+            // Pre-call classifier router for stream: opt-in, fails open. Runs before
+            // the request router so it takes precedence.
+            await this.applyClassifierRouting(options, originalPrompt, !options.disableTools &&
+                (!!(options.tools && Object.keys(options.tools).length > 0) ||
+                    this.getCustomTools().size > 0), !!(options.input?.images && options.input.images.length > 0), options
+                .thinking?.thinkingLevel);
             // Pre-call request router for stream: opt-in, fails open.
             await this.applyRequestRouter(options, originalPrompt, !options.disableTools &&
                 (!!(options.tools && Object.keys(options.tools).length > 0) ||

package/dist/providers/googleVertex.d.ts

@@ -1,8 +1,10 @@
 import type { ZodType } from "zod";
 import { AIProviderName } from "../constants/enums.js";
 import { BaseProvider } from "../core/baseProvider.js";
-import type { EnhancedGenerateResult, TextGenerationOptions, StreamOptions, StreamResult } from "../types/index.js";
+import type { EnhancedGenerateResult, TextGenerationOptions, StreamOptions, StreamResult, VertexAnthropicMessage, ChatMessage, MinimalChatMessage } from "../types/index.js";
 import type { Schema, LanguageModel } from "../types/index.js";
+export declare function buildAnthropicHistoryMessages(conversationMessages: Array<ChatMessage | MinimalChatMessage>): VertexAnthropicMessage[];
+export declare function appendUserMessage(messages: VertexAnthropicMessage[], content: VertexAnthropicMessage["content"]): void;
 /**
  * Recursively strip JSON-schema fields that Vertex Gemini's function-call AND
  * `responseSchema` (structured output) validators reject with 400

package/dist/providers/googleVertex.js

@@ -44,6 +44,144 @@ const hasAnthropicSupport = () => {
     // Actual availability is checked at runtime when creating the client
     return true;
 };
+// Parse stored rows into ordered segments, grouping tool_call/tool_result by (turn, step).
+function collectHistorySegments(conversationMessages) {
+    const segments = [];
+    const stepMap = new Map();
+    let turnCounter = 0;
+    const getStep = (stepIndex) => {
+        const key = `${turnCounter}:${stepIndex ?? "x"}`;
+        let step = stepMap.get(key);
+        if (!step) {
+            step = { type: "tool_step", callParts: [], resultParts: [] };
+            stepMap.set(key, step);
+            segments.push(step);
+        }
+        return step;
+    };
+    for (const msg of conversationMessages) {
+        if (msg.role === "tool_call") {
+            getStep(msg.metadata?.stepIndex).callParts.push({
+                name: msg.tool || "unknown",
+                input: msg.args || {},
+            });
+            continue;
+        }
+        if (msg.role === "tool_result") {
+            getStep(msg.metadata?.stepIndex).resultParts.push(msg.content && msg.content.length > 0 ? msg.content : "(no output)");
+            continue;
+        }
+        const role = msg.role === "assistant"
+            ? "assistant"
+            : msg.role === "user"
+                ? "user"
+                : null;
+        if (!role || !msg.content || msg.content.trim().length === 0) {
+            continue;
+        }
+        // New turn → fresh step namespace for any following tool rows.
+        turnCounter++;
+        segments.push({ type: "regular", role, parts: [msg.content] });
+    }
+    return segments;
+}
+// Append blocks to the trailing turn if it shares the role, else start a new turn.
+function pushTurn(messages, role, blocks) {
+    const last = messages[messages.length - 1];
+    if (last && last.role === role && Array.isArray(last.content)) {
+        last.content.push(...blocks);
+    }
+    else {
+        messages.push({ role, content: [...blocks] });
+    }
+}
+// Pair a tool step's calls/results by position; unbalanced extras are dropped
+// because Anthropic 400s on an orphaned tool_use/tool_result reference.
+function pairToolStep(step, ordinal) {
+    const calls = step.callParts;
+    const resultStrings = step.resultParts;
+    const paired = Math.min(calls.length, resultStrings.length);
+    if (paired !== calls.length || paired !== resultStrings.length) {
+        logger.debug("[GoogleVertex] Unbalanced tool step in Claude history replay", {
+            calls: calls.length,
+            results: resultStrings.length,
+            paired,
+        });
+    }
+    const uses = [];
+    const results = [];
+    for (let i = 0; i < paired; i++) {
+        const id = `hist_${ordinal}_${i}`;
+        uses.push({
+            type: "tool_use",
+            id,
+            name: calls[i].name,
+            input: calls[i].input,
+        });
+        results.push({
+            type: "tool_result",
+            tool_use_id: id,
+            content: resultStrings[i],
+        });
+    }
+    return { uses, results };
+}
+// Drop leading turns until the first is a real user turn — Anthropic requires it
+// (covers a leading assistant/tool step and an orphaned tool_result-only turn).
+function trimLeadingNonUser(messages) {
+    const isToolResultOnly = (m) => Array.isArray(m.content) &&
+        m.content.length > 0 &&
+        m.content.every((block) => block.type === "tool_result");
+    while (messages.length > 0 &&
+        (messages[0].role !== "user" || isToolResultOnly(messages[0]))) {
+        messages.shift();
+    }
+}
+// Rebuild Anthropic history with paired tool_use/tool_result turns from stored rows.
+export function buildAnthropicHistoryMessages(conversationMessages) {
+    const messages = [];
+    let stepOrdinal = 0;
+    for (const seg of collectHistorySegments(conversationMessages)) {
+        if (seg.type === "regular") {
+            pushTurn(messages, seg.role === "assistant" ? "assistant" : "user", [
+                { type: "text", text: String(seg.parts[0] ?? "") },
+            ]);
+            continue;
+        }
+        const { uses, results } = pairToolStep(seg, stepOrdinal);
+        if (uses.length === 0) {
+            continue;
+        }
+        stepOrdinal++;
+        pushTurn(messages, "assistant", uses);
+        pushTurn(messages, "user", results);
+    }
+    trimLeadingNonUser(messages);
+    if (logger.shouldLog("debug")) {
+        const blocks = messages.flatMap((m) => Array.isArray(m.content) ? m.content : []);
+        logger.debug("[GoogleVertex] Replayed Claude history with tool turns", {
+            historyMessages: messages.length,
+            toolUseBlocks: blocks.filter((b) => b.type === "tool_use").length,
+            toolResultBlocks: blocks.filter((b) => b.type === "tool_result").length,
+        });
+    }
+    return messages;
+}
+// Append the live user turn, merging into a trailing user turn to avoid back-to-back user messages.
+export function appendUserMessage(messages, content) {
+    const last = messages[messages.length - 1];
+    if (last && last.role === "user") {
+        const head = Array.isArray(last.content)
+            ? last.content
+            : [{ type: "text", text: last.content }];
+        const tail = Array.isArray(content)
+            ? content
+            : [{ type: "text", text: content }];
+        last.content = [...head, ...tail];
+        return;
+    }
+    messages.push({ role: "user", content });
+}
 /**
  * Recursively strip JSON-schema fields that Vertex Gemini's function-call AND
  * `responseSchema` (structured output) validators reject with 400
@@ -2287,18 +2425,14 @@ export class GoogleVertexProvider extends BaseProvider {
         });
         // Build messages from input
         const messages = [];
-        // Add conversation history if present.
-        //
-        // Intentionally text-only. Anthropic's API rejects messages where a
-        // tool_use_id reference appears without its matching tool_use in the
-        // same turn — so synthesising tool_use / tool_result blocks from
-        // stored ChatMessages risks emitting orphaned references that fail
-        // validation. Tool rows are still persisted to Redis (chat-history
-        // UI renders them) but they don't re-enter the model's context on
-        // subsequent turns.
+        // Replay conversationMessages (with tool turns), else the legacy text-only conversationHistory.
         if (options.conversationMessages &&
             options.conversationMessages.length > 0) {
-            for (const msg of options.conversationMessages) {
+            messages.push(...buildAnthropicHistoryMessages(options.conversationMessages));
+        }
+        else if (options.conversationHistory &&
+            options.conversationHistory.length > 0) {
+            for (const msg of options.conversationHistory) {
                 if (msg.role === "user" || msg.role === "assistant") {
                     messages.push({
                         role: msg.role,
@@ -2430,13 +2564,10 @@ export class GoogleVertexProvider extends BaseProvider {
             type: "text",
             text: multimodalInput.text,
         });
-        // Add the user message with appropriate content format
-        messages.push({
-            role: "user",
-            content: userContentParts.length === 1 && userContentParts[0].type === "text"
-                ? multimodalInput.text
-                : userContentParts,
-        });
+        // Append the live user turn (merges into a trailing user turn if present).
+        appendUserMessage(messages, userContentParts.length === 1 && userContentParts[0].type === "text"
+            ? multimodalInput.text
+            : userContentParts);
         // Convert tools to Anthropic format if present
         let tools;
         const executeMap = new Map();
@@ -3056,20 +3187,14 @@ export class GoogleVertexProvider extends BaseProvider {
         // Build messages from input
         const messages = [];
         const inputText = options.prompt || options.input?.text || "Please respond.";
-        // Add conversation history if present. Prefer `conversationMessages`
-        // (what NeuroLink core injects today via MessageBuilder) and fall back
-        // to the legacy `conversationHistory` field for callers that still use
-        // the older surface. The Vertex Claude STREAM path already follows this
-        // priority — keeping the GENERATE path on `conversationHistory` only
-        // would silently drop multi-turn context for memory/loop sessions.
-        // Intentionally text-only: see the stream sibling for the rationale —
-        // synthesising tool_use / tool_result blocks from stored ChatMessages
-        // risks emitting orphaned references that Anthropic's API rejects.
-        const historyMessages = options.conversationMessages && options.conversationMessages.length > 0
-            ? options.conversationMessages
-            : options.conversationHistory;
-        if (historyMessages && historyMessages.length > 0) {
-            for (const msg of historyMessages) {
+        // Replay conversationMessages (with tool turns), else the legacy text-only conversationHistory.
+        if (options.conversationMessages &&
+            options.conversationMessages.length > 0) {
+            messages.push(...buildAnthropicHistoryMessages(options.conversationMessages));
+        }
+        else if (options.conversationHistory &&
+            options.conversationHistory.length > 0) {
+            for (const msg of options.conversationHistory) {
                 if (msg.role === "user" || msg.role === "assistant") {
                     messages.push({
                         role: msg.role,
@@ -3201,13 +3326,10 @@ export class GoogleVertexProvider extends BaseProvider {
             type: "text",
             text: inputText,
         });
-        // Add the user message with appropriate content format
-        messages.push({
-            role: "user",
-            content: userContentParts.length === 1 && userContentParts[0].type === "text"
-                ? inputText
-                : userContentParts,
-        });
+        // Append the live user turn (merges into a trailing user turn if present).
+        appendUserMessage(messages, userContentParts.length === 1 && userContentParts[0].type === "text"
+            ? inputText
+            : userContentParts);
         // Convert tools to Anthropic format if present
         let tools;
         const executeMap = new Map();

package/dist/routing/classifierRouter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * ClassifierRouter — the single "classify → pick model + tools → run" engine.
+ *
+ * Given a request snapshot it (1) classifies difficulty (heuristic or a cheap
+ * LLM), (2) selects the best provider/model from the host-declared base pool —
+ * cheaper/faster for easy tiers, more capable for hard tiers — enriching pool
+ * members with real cost/quality metadata from the model registry, and
+ * (3) narrows the tool set via per-difficulty directives or classifier hints.
+ *
+ * Pure of provider imports (mirrors ModelPool): the LLM caller is injected.
+ * The only data dependency is the read-only `ModelResolver` registry lookup,
+ * used purely for metadata enrichment and never for provider construction.
+ */
+import type { ClassifierRouterConfig, ClassifierRouterDecision, ClassifierRouterDeps, ClassifierRouterInput } from "../types/index.js";
+export declare class ClassifierRouter {
+    private readonly config;
+    private readonly deps;
+    private readonly metaCache;
+    constructor(config: ClassifierRouterConfig, deps?: ClassifierRouterDeps);
+    /**
+     * Classify the request and produce a combined model + tool decision, or
+     * `null` when nothing should change. Never throws (fails open).
+     */
+    route(input: ClassifierRouterInput): Promise<ClassifierRouterDecision | null>;
+    /** Run the configured strategy; LLM falls back to heuristic on failure. */
+    private classify;
+    /**
+     * Build LLM-facing model descriptors + an id→member map so the classifier can
+     * pick a model directly. Works for ANY pool, registry-backed or not.
+     */
+    private buildCandidates;
+    /**
+     * Resolve the ranked model list for a decision. Prefers the LLM's direct pick
+     * (`selectedModelId`); otherwise falls back to difficulty-based tierMap /
+     * metadata scoring.
+     */
+    private selectModels;
+    /** Candidate members for a difficulty: explicit tierMap or eligible pool. */
+    private candidatesFor;
+    /** Drop members that cannot satisfy the required capabilities (lenient). */
+    private filterByCapabilities;
+    /** Rank candidates best-first for the difficulty's strategy. */
+    private rank;
+    /** Tool narrowing: per-difficulty directive, then classifier hints. */
+    private selectTools;
+    /**
+     * Resolve cost/quality/capabilities for a member. Declared values win;
+     * gaps are filled from the model registry (by model name/alias) when known.
+     * Results are cached per (provider/model) for the router's lifetime.
+     */
+    private metaFor;
+}