@juspay/neurolink 12.18.1 → 12.19.0

package/dist/context/contextDecision.js

@@ -0,0 +1,234 @@
+/**
+ * Relevance-driven context compaction.
+ *
+ * Every stage of the existing compactor is *positional*: prune protects the
+ * most recent 40K tokens, truncation drops the oldest half, summarization
+ * keeps a trailing ratio. None of them has any notion of what the current
+ * request is about, so a fifty-turn conversation that ends with "now rename
+ * that variable" keeps the forty turns about database migrations and drops
+ * nothing that matters less.
+ *
+ * A decision model changes the economics of asking. Latency is flat in
+ * question count — one question and four hundred questions cost the same
+ * round trip — so "is this message needed to answer the current request?" can
+ * be asked about *every* message at once, for about $0.00002.
+ *
+ * What it must never do is lose something the turn needed. The guards below
+ * are therefore deliberately conservative, and every one of them is a veto:
+ *
+ * - only plain user/assistant text is ever eligible; tool calls, tool
+ *   results, summaries, pinned skills and system messages are untouchable,
+ *   because dropping half of a tool-call pair produces a malformed request
+ *   rather than a smaller one
+ * - the most recent messages are never eligible, whatever the model says
+ * - a message is dropped only on a CONFIDENT no, never on silence or a
+ *   near-coin-flip
+ * - at most a bounded fraction of eligible messages may go in one pass
+ *
+ * @module context/contextDecision
+ */
+import { decisionKey, gateDecisionBoolean } from "../utils/decisionAnswers.js";
+import { logger } from "../utils/logger.js";
+const MESSAGE_NAMESPACE = "msg";
+/** Messages at the tail that are never eligible, whatever the model says. */
+const DEFAULT_PROTECT_RECENT = 6;
+/** Ceiling on the share of eligible messages one pass may drop. */
+const DEFAULT_MAX_DROP_RATIO = 0.5;
+/**
+ * How sure the model must be that a message is irrelevant. High, for the same
+ * reason the tool router's bar is high: keeping a useless message costs
+ * tokens, losing a needed one costs the answer.
+ */
+const DEFAULT_MIN_DROP_CONFIDENCE = 0.6;
+/** Never ask about more than this many messages in one request. */
+const MAX_QUESTIONS = 300;
+/** Per-message text sent as state. Enough to judge, bounded enough to batch. */
+const MAX_MESSAGE_CHARS = 1200;
+const RELEVANCE_INSTRUCTIONS = "This earlier message contains information the assistant still needs in order to answer the current request correctly. Treat it as needed if it states a requirement, a decision, a constraint, a correction, a name, a number, or a preference that the current request builds on. Treat it as not needed if the current request is about something else entirely, or if the message is small talk, an acknowledgement, or superseded by a later message.";
+/**
+ * A message is eligible for relevance-based dropping only if losing it cannot
+ * corrupt the request. That rules out far more than it keeps, on purpose.
+ */
+function isEligible(message) {
+    if (message.role !== "user" && message.role !== "assistant") {
+        return false;
+    }
+    if (typeof message.content !== "string" || message.content.trim() === "") {
+        return false;
+    }
+    // A summary already represents messages that were dropped; dropping it
+    // discards all of them at once.
+    if (message.metadata?.isSummary) {
+        return false;
+    }
+    // Pinned skill instructions are replayed verbatim by design and are already
+    // protected from truncation.
+    if (message.metadata?.isSkill) {
+        return false;
+    }
+    // Assistant turns that carry tool calls pair with a tool_result elsewhere.
+    if (message.tool || message.toolCallId || message.events?.length) {
+        return false;
+    }
+    if (message.isTruncationMarker || message.condenseParent) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Ask which earlier messages the current request still needs, and return the
+ * ones to drop.
+ *
+ * Returns `null` when nothing should change — no decision provider, a failed
+ * call, nothing eligible, or no confident drop. A null return is the signal
+ * to carry on with positional compaction exactly as before.
+ */
+export async function selectIrrelevantMessages(messages, currentRequest, decide, options) {
+    const protectRecent = options?.protectRecent ?? DEFAULT_PROTECT_RECENT;
+    const minConfidence = options?.minDropConfidence ?? DEFAULT_MIN_DROP_CONFIDENCE;
+    const maxDropRatio = options?.maxDropRatio ?? DEFAULT_MAX_DROP_RATIO;
+    const cutoff = Math.max(0, messages.length - protectRecent);
+    const eligible = messages
+        .map((message, index) => ({ message, index }))
+        .filter(({ message, index }) => index < cutoff && isEligible(message))
+        .slice(0, MAX_QUESTIONS);
+    if (eligible.length === 0 || !currentRequest.trim()) {
+        return null;
+    }
+    const questions = {};
+    eligible.forEach((entry, position) => {
+        questions[decisionKey(MESSAGE_NAMESPACE, position)] = {
+            type: "boolean",
+            instructions: RELEVANCE_INSTRUCTIONS,
+            criteria: {
+                true: `The current request depends on this message: "${preview(entry.message)}"`,
+                false: "The current request does not depend on this message.",
+            },
+        };
+    });
+    const result = await decide({
+        state: {
+            current_request: currentRequest.slice(0, 4000),
+            conversation: eligible.map((entry, position) => ({
+                index: position,
+                role: entry.message.role,
+                text: preview(entry.message),
+            })),
+        },
+        questions,
+        timeoutMs: options?.timeoutMs,
+    });
+    if (!result) {
+        return null;
+    }
+    const dropCandidates = [];
+    let answered = 0;
+    eligible.forEach((entry, position) => {
+        const verdict = gateDecisionBoolean(result.answers, decisionKey(MESSAGE_NAMESPACE, position), { minConfidence });
+        if (verdict !== undefined) {
+            answered += 1;
+        }
+        if (verdict === false) {
+            dropCandidates.push(entry.index);
+        }
+    });
+    if (answered === 0 || dropCandidates.length === 0) {
+        return null;
+    }
+    // Cap how much one pass may remove. Beyond this the model is more likely to
+    // have misread the request than to be right about most of the conversation,
+    // and positional compaction is the safer tool for a wholesale reduction.
+    //
+    // `dropCandidates` is built by walking `eligible` oldest-first, so slicing
+    // from the front drops the OLDEST candidates and spares the newest when the
+    // cap binds — the same recency assumption every other stage makes.
+    const maxDrops = Math.floor(eligible.length * maxDropRatio);
+    const droppedIndices = dropCandidates.slice(0, Math.max(0, maxDrops));
+    if (droppedIndices.length === 0) {
+        return null;
+    }
+    const dropSet = new Set(droppedIndices);
+    const kept = messages.filter((_, index) => !dropSet.has(index));
+    logger.info("[Compaction] Stage 0 (relevance)", {
+        model: result.model,
+        latencyMs: result.latencyMs,
+        askedCount: eligible.length,
+        answeredCount: answered,
+        droppedCount: droppedIndices.length,
+        cappedFrom: dropCandidates.length,
+    });
+    return {
+        messages: kept,
+        droppedIndices,
+        askedCount: eligible.length,
+        answeredCount: answered,
+        model: result.model,
+        latencyMs: result.latencyMs,
+    };
+}
+/**
+ * Gate a generated summary before it replaces the messages it covers.
+ *
+ * Stage 3 accepts any non-empty string today, so a summarizer that returned
+ * an apology, a refusal, or a truncated fragment silently destroys the
+ * conversation it was meant to preserve — and the messages are gone by the
+ * time anyone reads the summary.
+ *
+ * Returns `true` when the summary may be used and `false` only on a confident
+ * rejection. Anything else — no decision provider, a failed call, an
+ * unanswered or uncertain verdict — returns `true`, because refusing a
+ * summary means falling through to truncation, which loses strictly more.
+ */
+export async function summaryPreservesContext(summary, replacedMessages, decide, options) {
+    if (!summary.trim() || replacedMessages.length === 0) {
+        return true;
+    }
+    const result = await decide({
+        state: {
+            summary: summary.slice(0, 12000),
+            original_messages: replacedMessages.slice(-60).map((message) => ({
+                role: message.role,
+                text: preview(message),
+            })),
+        },
+        questions: {
+            preserves: {
+                type: "boolean",
+                instructions: "The summary preserves every decision, requirement, constraint, correction and open question from the original messages. Nothing that a later turn could need has been dropped.",
+            },
+            is_refusal: {
+                type: "boolean",
+                instructions: "The summary is not a summary at all — it is an apology, a refusal, an error message, or a request for clarification.",
+            },
+        },
+        timeoutMs: options?.timeoutMs,
+    });
+    if (!result) {
+        return true;
+    }
+    const minConfidence = options?.minConfidence ?? 0.6;
+    const refusal = gateDecisionBoolean(result.answers, "is_refusal", {
+        minConfidence,
+    });
+    if (refusal === true) {
+        logger.warn("[Compaction] Summary rejected — not a summary", {
+            model: result.model,
+        });
+        return false;
+    }
+    const preserves = gateDecisionBoolean(result.answers, "preserves", {
+        minConfidence,
+    });
+    if (preserves === false) {
+        logger.warn("[Compaction] Summary rejected — loses required context", {
+            model: result.model,
+            messageCount: replacedMessages.length,
+        });
+        return false;
+    }
+    return true;
+}
+/** Bounded text for one message, used in both state and criteria. */
+function preview(message) {
+    return message.content.slice(0, MAX_MESSAGE_CHARS);
+}

package/dist/core/baseProvider.d.ts

@@ -1,7 +1,7 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "../index.js";
 import type { NeuroLink } from "../neurolink.js";
-import type { UnknownRecord, MiddlewareFactoryOptions, StreamOptions, StreamResult, AIProvider, AnalyticsData, EnhancedGenerateResult, TextGenerationOptions, TextGenerationResult, ValidationSchema, EmbedInput } from "../types/index.js";
+import type { UnknownRecord, MiddlewareFactoryOptions, StreamOptions, StreamResult, AIProvider, AnalyticsData, EnhancedGenerateResult, TextGenerationOptions, TextGenerationResult, ValidationSchema, EmbedInput, DecisionRequest, DecisionResult } from "../types/index.js";
 import { TelemetryHandler } from "./modules/TelemetryHandler.js";
 import type { LanguageModel, ModelMessage, RawUsageObject, Tool, ToolCallRepairFunction, ToolSet } from "../types/index.js";
 export declare abstract class BaseProvider implements AIProvider {
@@ -358,6 +358,30 @@ export declare abstract class BaseProvider implements AIProvider {
      * @returns The default embedding model name, or undefined if not supported
      */
     protected getDefaultEmbeddingModel(): string | undefined;
+    /**
+     * Evaluate a state against a batch of typed questions.
+     *
+     * Default implementation throws, exactly as `embed()` does: `decide` is an
+     * optional capability, declared per provider by `"decide"` in its
+     * descriptor's `inferenceKinds`. Callers that want a silent no-op on an
+     * unsupporting provider should check the descriptor first rather than
+     * catching this.
+     *
+     * Latency on a decision model is flat in question count while concurrent
+     * requests queue, so this method is deliberately batch-shaped: one call
+     * carries every question a caller needs. There is no single-question
+     * convenience wrapper, because it would invite fanning out.
+     *
+     * @throws Error if the provider does not serve the `decide` inference type
+     */
+    decide(_request: DecisionRequest): Promise<DecisionResult>;
+    /**
+     * Get the default decision model for this provider.
+     *
+     * Mirrors {@link getDefaultEmbeddingModel}. Returns undefined for providers
+     * that do not serve the `decide` inference type.
+     */
+    protected getDefaultDecisionModel(): string | undefined;
     /**
      * Create an `experimental_repairToolCall` handler for streamText/generateText.
      * Dynamically reads the tool's JSON schema to repair wrong names and params.
@@ -441,6 +465,8 @@ export declare abstract class BaseProvider implements AIProvider {
      * that call `withTurnTimeout` directly.
      */
     protected getDescriptorGenerateMs(): number | undefined;
+    /** Per-provider `decide` budget from the descriptor, when one is declared. */
+    protected getDescriptorDecideMs(): number | undefined;
     protected abstract getAISDKModel(): LanguageModel | Promise<LanguageModel>;
     /**
      * Public handle on this provider's model object.

package/dist/core/baseProvider.js

@@ -1833,6 +1833,40 @@ export class BaseProvider {
         return undefined;
     }
     // ===================
+    // `decide` inference type
+    // ===================
+    /**
+     * Evaluate a state against a batch of typed questions.
+     *
+     * Default implementation throws, exactly as `embed()` does: `decide` is an
+     * optional capability, declared per provider by `"decide"` in its
+     * descriptor's `inferenceKinds`. Callers that want a silent no-op on an
+     * unsupporting provider should check the descriptor first rather than
+     * catching this.
+     *
+     * Latency on a decision model is flat in question count while concurrent
+     * requests queue, so this method is deliberately batch-shaped: one call
+     * carries every question a caller needs. There is no single-question
+     * convenience wrapper, because it would invite fanning out.
+     *
+     * @throws Error if the provider does not serve the `decide` inference type
+     */
+    async decide(_request) {
+        logger.warn(`decide() called on ${this.providerName}, which does not serve the decide inference type`);
+        throw new Error(`The decide inference type is not supported by the ${this.providerName} provider. ` +
+            `Supported providers: typesafe. A provider declares this capability with ` +
+            `"decide" in its descriptor's inferenceKinds.`);
+    }
+    /**
+     * Get the default decision model for this provider.
+     *
+     * Mirrors {@link getDefaultEmbeddingModel}. Returns undefined for providers
+     * that do not serve the `decide` inference type.
+     */
+    getDefaultDecisionModel() {
+        return undefined;
+    }
+    // ===================
     // ===================
     // BZ-665: Schema-driven tool call repair
     // ===================
@@ -1988,6 +2022,11 @@ export class BaseProvider {
         return PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName)?.timeouts
             ?.generateMs;
     }
+    /** Per-provider `decide` budget from the descriptor, when one is declared. */
+    getDescriptorDecideMs() {
+        return PROVIDER_DESCRIPTORS_BY_NAME.get(this.providerName)?.timeouts
+            ?.decideMs;
+    }
     /**
      * Public handle on this provider's model object.
      *

package/dist/core/toolRouting.d.ts

@@ -25,6 +25,14 @@
  * Tool granularity (ITEM D): when `params.granularity === "tool"`, individual
  * unpicked tools are excluded rather than whole servers. Falls back to "server"
  * if the embedding path is disabled or fails.
+ *
+ * Decision router: when `params.decideFn` is supplied AND a decision provider
+ * is configured, one calibrated yes/no question per server replaces the router
+ * LLM call — ~400ms against a 15s budget, and a probability per server rather
+ * than a list that cannot express doubt. It runs after the embedding
+ * fast-path and before the LLM router, and returning null from it falls
+ * through to the LLM path unchanged. See `toolRoutingDecision.ts` for why a
+ * server is only ever dropped on a CONFIDENT no.
  */
 import type { ToolRoutingCatalogEntry, ToolRoutingResolutionParams, ToolRoutingServerDescriptor } from "../types/index.js";
 /**

package/dist/core/toolRouting.js

@@ -25,11 +25,20 @@
  * Tool granularity (ITEM D): when `params.granularity === "tool"`, individual
  * unpicked tools are excluded rather than whole servers. Falls back to "server"
  * if the embedding path is disabled or fails.
+ *
+ * Decision router: when `params.decideFn` is supplied AND a decision provider
+ * is configured, one calibrated yes/no question per server replaces the router
+ * LLM call — ~400ms against a 15s budget, and a probability per server rather
+ * than a list that cannot express doubt. It runs after the embedding
+ * fast-path and before the LLM router, and returning null from it falls
+ * through to the LLM path unchanged. See `toolRoutingDecision.ts` for why a
+ * server is only ever dropped on a CONFIDENT no.
  */
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
 import { withTimeout } from "../utils/async/index.js";
 import { selectRelevantToolNames } from "./toolRoutingEmbedding.js";
+import { selectServersByDecision } from "./toolRoutingDecision.js";
 const routerOutputSchema = z.object({
     servers: z.array(z.string()),
 });
@@ -290,7 +299,7 @@ async function runEmbeddingFastPath(userQuery, routableServers, alwaysIncludeSer
  * 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, emitDecision, 
+    const { catalog, alwaysIncludeServerIds, userQuery, routerPromptPrefix, routerModel, timeoutMs, generateFn, decideFn, decisionMinDropConfidence, emitDecision, 
     // L2 / ITEM D parameters (all optional — omitting reproduces today's behavior)
     embedFn, embeddingConfig, granularity = "server", embeddingVectorCache, } = params;
     const routableServers = catalog.filter((server) => !alwaysIncludeServerIds.includes(server.id));
@@ -365,6 +374,7 @@ export async function resolveToolRoutingExclusions(params) {
                     embeddingActivated: true,
                     candidateToolCount: embResult.candidateToolCount,
                     granularity: embResult.granularity,
+                    strategy: "embedding",
                 });
                 return embResult.excludedToolNames;
             }
@@ -372,6 +382,19 @@ export async function resolveToolRoutingExclusions(params) {
             // fall through to the LLM-router path below.
         }
         // -------------------------------------------------------------------------
+        // DECISION-MODEL ROUTER — runs when a decision provider is configured
+        // -------------------------------------------------------------------------
+        // Placed after the embedding fast-path (which is cheaper still and only
+        // activates on large catalogs) and before the generative router, which it
+        // replaces: one yes/no question per server, ~400ms, calibrated per server.
+        // Any null return falls through to the LLM path below unchanged.
+        if (decideFn) {
+            const decided = await runDecisionRouter(userQuery, routableServers, decideFn, decisionMinDropConfidence, routingStartTime, emitDecision);
+            if (decided) {
+                return decided;
+            }
+        }
+        // -------------------------------------------------------------------------
         // EXISTING LLM ROUTER PATH (L3) — runs when embedding is off or fell back
         // -------------------------------------------------------------------------
         const routerPrompt = buildRouterPrompt(userQuery, routableServers, routerPromptPrefix);
@@ -467,6 +490,7 @@ export async function resolveToolRoutingExclusions(params) {
             cacheHit: false,
             durationMs: Date.now() - routingStartTime,
             granularity: "server",
+            strategy: "llm",
         });
         return excludedToolNames;
     }
@@ -493,3 +517,30 @@ export async function resolveToolRoutingExclusions(params) {
         return [];
     }
 }
+/**
+ * Decision-model routing path, kept out of `resolveToolRoutingExclusions` so
+ * that function stays readable as a list of strategies rather than growing a
+ * fourth inline block.
+ *
+ * Returns the exclusion list when the decision router produced one, or `null`
+ * to fall through to the generative router unchanged.
+ */
+async function runDecisionRouter(userQuery, routableServers, decideFn, minDropConfidence, routingStartTime, emitDecision) {
+    const decided = await selectServersByDecision(userQuery, routableServers, decideFn, { minDropConfidence });
+    if (!decided) {
+        return null;
+    }
+    safeEmitDecision(emitDecision, {
+        outcome: "applied",
+        selectedServerIds: decided.selectedServerIds,
+        excludedServerIds: decided.excludedServerIds,
+        hallucinatedIds: [],
+        excludedToolCount: decided.excludedToolNames.length,
+        routableServerCount: routableServers.length,
+        cacheHit: false,
+        durationMs: Date.now() - routingStartTime,
+        granularity: "server",
+        strategy: "decision",
+    });
+    return decided.excludedToolNames;
+}

package/dist/core/toolRoutingDecision.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Tool routing by decision model.
+ *
+ * The shipped router asks a generative model for `{servers: string[]}` on a
+ * 15-second budget. That shape cannot express uncertainty: a server is in the
+ * list or it is not, and the only recourse for a model that is unsure is to
+ * include it. A decision model answers one yes/no question per server and
+ * returns a *calibrated probability* for each, in one round trip of ~400ms
+ * costing ~$0.00002.
+ *
+ * The asymmetry that follows is the whole point. Keeping a server that was not
+ * needed costs a few hundred tokens of tool definitions. Dropping a server
+ * that WAS needed costs the turn — the model cannot call a tool it was never
+ * shown, and it has no way to ask for it back. So a server is excluded only on
+ * a *confident no*; unanswered, mistyped and near-coin-flip answers all keep
+ * it. This is the same reasoning as the classifier's asymmetric upgrade and
+ * downgrade bars, applied to a different decision.
+ *
+ * Fail-open in every direction: returns `null` whenever the caller should
+ * carry on as if this module did not exist.
+ *
+ * @module core/toolRoutingDecision
+ */
+import type { DecisionCallerFn, ToolRoutingCatalogEntry, ToolRoutingDecisionOutcome } from "../types/index.js";
+/**
+ * Ask one yes/no question per routable server and return the servers to keep.
+ *
+ * Returns `null` when the caller should fall through to its existing path:
+ * no decision provider, a failed call, fewer than two servers, or an answer
+ * set that would change nothing.
+ */
+export declare function selectServersByDecision(userQuery: string, routableServers: ToolRoutingCatalogEntry[], decide: DecisionCallerFn, options?: {
+    timeoutMs?: number;
+    minDropConfidence?: number;
+}): Promise<ToolRoutingDecisionOutcome | null>;

package/dist/core/toolRoutingDecision.js

@@ -0,0 +1,194 @@
+/**
+ * Tool routing by decision model.
+ *
+ * The shipped router asks a generative model for `{servers: string[]}` on a
+ * 15-second budget. That shape cannot express uncertainty: a server is in the
+ * list or it is not, and the only recourse for a model that is unsure is to
+ * include it. A decision model answers one yes/no question per server and
+ * returns a *calibrated probability* for each, in one round trip of ~400ms
+ * costing ~$0.00002.
+ *
+ * The asymmetry that follows is the whole point. Keeping a server that was not
+ * needed costs a few hundred tokens of tool definitions. Dropping a server
+ * that WAS needed costs the turn — the model cannot call a tool it was never
+ * shown, and it has no way to ask for it back. So a server is excluded only on
+ * a *confident no*; unanswered, mistyped and near-coin-flip answers all keep
+ * it. This is the same reasoning as the classifier's asymmetric upgrade and
+ * downgrade bars, applied to a different decision.
+ *
+ * Fail-open in every direction: returns `null` whenever the caller should
+ * carry on as if this module did not exist.
+ *
+ * @module core/toolRoutingDecision
+ */
+import { decisionKey, gateDecisionBoolean } from "../utils/decisionAnswers.js";
+import { logger } from "../utils/logger.js";
+/** Namespace for the per-server questions in the batch. */
+const SERVER_NAMESPACE = "server";
+/**
+ * How confidently the model must answer "no" before a server's tools are
+ * withheld. Deliberately high — a wrongly dropped server breaks the turn,
+ * while a wrongly kept one costs tokens.
+ */
+const DEFAULT_MIN_DROP_CONFIDENCE = 0.6;
+/**
+ * Upper bound on the query text sent as state. The query is untrusted and may
+ * attempt injection; the blast radius is bounded (the worst outcome is keeping
+ * MORE already-registered tools, since ids are never read back off the wire —
+ * answers are matched by position), but an unbounded state would still be
+ * billed and could push the request past the model's input ceiling.
+ */
+const MAX_STATE_CHARS = 10000;
+/**
+ * Cap on servers asked about in one batch. Latency is flat in question count,
+ * so this is purely an input-size guard: state plus all questions must stay
+ * under the ~64K request ceiling.
+ */
+const MAX_SERVERS = 200;
+/**
+ * The question wording, and why it is this wording.
+ *
+ * The obvious phrasing — "answering this request will require calling at least
+ * one tool from this server", with a `false` criterion reading "this server is
+ * unrelated, OR the request needs no tool at all" — was measured against a
+ * 10-request × 5-server labelled set. It separated correctly but weakly:
+ * unrelated servers averaged p=0.31 and reached 0.80, so at the 0.6 drop bar
+ * only 12 of 39 unneeded servers were dropped.
+ *
+ * Naming the server, asking in the present tense about what carrying out the
+ * request *involves*, and splitting the bundled `false` criterion into a single
+ * claim moved unrelated servers to a mean of p=0.03 with a maximum of 0.35 —
+ * **37 of 39** dropped at the same bar, still with zero wrong drops.
+ *
+ * The lesson generalises: a decision model reads literally, and an `or` in a
+ * criterion is two questions wearing one coat.
+ */
+function serverQuestion(server) {
+    const does = uncapitalize(describeServer(server));
+    return {
+        type: "boolean",
+        instructions: `The request needs the "${server.id}" server, which can ${does}.`,
+        criteria: {
+            true: `Carrying out the request involves ${does}.`,
+            false: `The request is about something else; nothing it asks for involves ${does}.`,
+        },
+    };
+}
+/**
+ * Lowercase only the FIRST character. A plain `toLowerCase()` would turn
+ * "Read and write GitHub issues" into "…github issues", and the proper noun is
+ * often the strongest signal in the sentence.
+ */
+function uncapitalize(text) {
+    // charAt rather than an index: it returns "" for an empty string, so this
+    // needs no length guard and no non-null assertion.
+    return text.charAt(0).toLowerCase() + text.slice(1);
+}
+/**
+ * Ask one yes/no question per routable server and return the servers to keep.
+ *
+ * Returns `null` when the caller should fall through to its existing path:
+ * no decision provider, a failed call, fewer than two servers, or an answer
+ * set that would change nothing.
+ */
+export async function selectServersByDecision(userQuery, routableServers, decide, options) {
+    if (!userQuery || routableServers.length < 2) {
+        return null;
+    }
+    const servers = routableServers.slice(0, MAX_SERVERS);
+    const questions = {};
+    servers.forEach((server, index) => {
+        questions[decisionKey(SERVER_NAMESPACE, index)] = serverQuestion(server);
+    });
+    const result = await decide({
+        // Structured state rather than a prompt string: the vendor accepts JSON,
+        // and naming the fields is what stops the model reading the catalogue as
+        // part of the user's request.
+        state: {
+            request: userQuery.slice(0, MAX_STATE_CHARS),
+            available_servers: servers.map((server) => ({
+                name: server.id,
+                does: describeServer(server),
+                tool_count: server.toolNames.length,
+            })),
+        },
+        questions,
+        timeoutMs: options?.timeoutMs,
+    });
+    if (!result) {
+        return null;
+    }
+    const minConfidence = options?.minDropConfidence ?? DEFAULT_MIN_DROP_CONFIDENCE;
+    const selectedServerIds = [];
+    const excludedServerIds = [];
+    let answered = 0;
+    servers.forEach((server, index) => {
+        const verdict = gateDecisionBoolean(result.answers, decisionKey(SERVER_NAMESPACE, index), { minConfidence });
+        if (verdict !== undefined) {
+            answered += 1;
+        }
+        // Only a confident `false` drops a server. `undefined` (unanswered, wrong
+        // type, or too close to a coin flip) and `true` both keep it.
+        if (verdict === false) {
+            excludedServerIds.push(server.id);
+        }
+        else {
+            selectedServerIds.push(server.id);
+        }
+    });
+    // Servers past the cap were never asked about, so they are kept — a server
+    // that was not offered to the model must never be dropped by its silence.
+    for (const server of routableServers.slice(MAX_SERVERS)) {
+        selectedServerIds.push(server.id);
+    }
+    if (answered === 0) {
+        logger.debug("[ToolRouting] Decision router returned no usable answers", {
+            routableServerCount: routableServers.length,
+        });
+        return null;
+    }
+    if (excludedServerIds.length === 0) {
+        // Nothing to exclude is indistinguishable from routing being off, and
+        // reporting it as "applied" would make the telemetry claim a narrowing
+        // that did not happen.
+        return null;
+    }
+    const excludedSet = new Set(excludedServerIds);
+    const excludedToolNames = routableServers
+        .filter((server) => excludedSet.has(server.id))
+        .flatMap((server) => server.toolNames);
+    logger.debug("[ToolRouting] Decision router applied", {
+        model: result.model,
+        latencyMs: result.latencyMs,
+        askedServerCount: servers.length,
+        answeredCount: answered,
+        keptServerCount: selectedServerIds.length,
+        excludedServerCount: excludedServerIds.length,
+        excludedToolCount: excludedToolNames.length,
+    });
+    return {
+        selectedServerIds,
+        excludedServerIds,
+        excludedToolNames,
+        answeredCount: answered,
+        model: result.model,
+        latencyMs: result.latencyMs,
+    };
+}
+/**
+ * One line describing what a server is for. Falls back to naming its tools
+ * when the host declared no description, since a bare id ("fs", "gh") carries
+ * almost no signal and the tool names usually carry a great deal.
+ */
+function describeServer(server) {
+    if (server.description && server.description.trim().length > 0) {
+        return server.description;
+    }
+    const names = server.toolNames
+        .map((name) => name.slice(server.id.length + 1))
+        .filter((name) => name.length > 0)
+        .slice(0, 12);
+    return names.length > 0
+        ? `provides the tools: ${names.join(", ")}`
+        : `the "${server.id}" server`;
+}