@juspay/neurolink 12.18.1 → 12.19.0

package/dist/routing/classifierRouter.js

@@ -11,8 +11,10 @@
  * The only data dependency is the read-only `ModelResolver` registry lookup,
  * used purely for metadata enrichment and never for provider construction.
  */
-import { classifyHeuristic, classifyLlm } from "./classifierStrategies.js";
+import { classifyHeuristic, classifyJev, classifyLlm, contextScopeToThreshold, CLASSIFIER_CONTEXT_SCOPES, } from "./classifierStrategies.js";
+import { buildModelCatalog, buildRegistryIndex, enrichCandidate, rankCatalogue, } from "./modelCatalog.js";
 import { ModelResolver } from "../models/modelResolver.js";
+import { resolveDefaultDecisionProvider } from "../factories/providerDescriptors.js";
 /** Maps a registry quality enum to a comparable numeric score. */
 const QUALITY_SCORE = { high: 3, medium: 2, low: 1 };
 /** How each difficulty ranks candidate members. */
@@ -34,9 +36,59 @@ export class ClassifierRouter {
     config;
     deps;
     metaCache = new Map();
+    /**
+     * The effective pool: what the host declared, plus catalogue-derived members
+     * when `catalog.enabled`. Mutable so a long-lived host can widen or narrow
+     * it without rebuilding the router — the constructor-frozen pool was the one
+     * thing preventing a runtime model catalogue.
+     */
+    pool;
+    /** Registry index for candidate enrichment; built once, on first use. */
+    registryIndex;
     constructor(config, deps = {}) {
         this.config = config;
         this.deps = deps;
+        this.pool = ClassifierRouter.composePool(config);
+    }
+    /**
+     * Merge the declared pool with the catalogue. Declared members win on a
+     * duplicate `provider/model`, because a host that spelled a member out has
+     * said something about it (a region, a description, an explicit tier) that
+     * the registry does not know.
+     */
+    static composePool(config) {
+        const declared = config.pool ?? [];
+        const catalogue = buildModelCatalog(config.catalog);
+        if (catalogue.length === 0) {
+            return [...declared];
+        }
+        const seen = new Set(declared.map((m) => m.id ?? `${m.provider}/${m.model ?? ""}`));
+        return [
+            ...declared,
+            ...catalogue.filter((m) => !seen.has(m.id ?? `${m.provider}/${m.model ?? ""}`)),
+        ];
+    }
+    /**
+     * Replace the routable pool at runtime. Returns the new size.
+     *
+     * Clears the metadata cache, since a member's declared cost/quality is
+     * cached per `provider::model` and a replacement pool may declare different
+     * values for the same pair.
+     */
+    setPool(members) {
+        this.pool = [...members];
+        this.metaCache.clear();
+        return this.pool.length;
+    }
+    /** The pool currently routed over, declared plus catalogue. */
+    getPool() {
+        return [...this.pool];
+    }
+    /** Rebuild the catalogue half of the pool (e.g. after credentials change). */
+    refreshCatalog() {
+        this.pool = ClassifierRouter.composePool(this.config);
+        this.metaCache.clear();
+        return this.pool.length;
     }
     /**
      * Classify the request and produce a combined model + tool decision, or
@@ -44,15 +96,21 @@ export class ClassifierRouter {
      */
     async route(input) {
         try {
-            // For the LLM strategy, hand the pool to the classifier so it can select
-            // a model directly — the generic path for custom/registry-less models.
-            const useLlm = this.config.classifier === "llm" && !!this.deps.generate;
-            const built = useLlm ? this.buildCandidates() : undefined;
-            const decision = await this.classify(input, built?.descriptors);
-            const ranked = this.selectModels(decision, built?.byId);
+            // Both the LLM and Jev strategies can pick a model straight out of the
+            // pool — the generic path for custom/registry-less models.
+            const strategy = this.resolveStrategy();
+            const usesCandidates = (strategy === "jev" && !!this.deps.decide) ||
+                (strategy === "llm" && !!this.deps.generate);
+            const built = usesCandidates ? this.buildCandidates() : undefined;
+            const decision = await this.classify(strategy, input, built?.descriptors);
+            const ranked = this.selectModels(decision, input, built?.byId);
             const primary = ranked[0];
             const { toolFilter, excludeTools } = this.selectTools(decision);
-            if (!primary && !toolFilter && !excludeTools) {
+            const compactionThreshold = this.selectContextBudget(decision);
+            if (!primary &&
+                !toolFilter &&
+                !excludeTools &&
+                compactionThreshold === undefined) {
                 return null;
             }
             return {
@@ -63,6 +121,8 @@ export class ClassifierRouter {
                 modelFallbacks: ranked.slice(1),
                 toolFilter,
                 excludeTools,
+                compactionThreshold,
+                contextScope: decision.contextScope,
                 reason: decision.reason,
             };
         }
@@ -73,9 +133,38 @@ export class ClassifierRouter {
             return null;
         }
     }
-    /** Run the configured strategy; LLM falls back to heuristic on failure. */
-    async classify(input, candidates) {
-        if (this.config.classifier === "llm" && this.deps.generate) {
+    /**
+     * Resolve "auto" (the default) to a concrete strategy. Jev is preferred the
+     * moment a TypeSafe key is present; without one the behaviour is exactly
+     * what it was before Jev existed.
+     */
+    resolveStrategy() {
+        const configured = this.config.classifier ?? "auto";
+        if (configured !== "auto") {
+            return configured;
+        }
+        // A decision provider that is both registered AND has its key set is the
+        // whole activation condition — this is where "if somebody sets it we
+        // start using it" lives for routing.
+        return this.deps.decide && resolveDefaultDecisionProvider()
+            ? "jev"
+            : "heuristic";
+    }
+    /** Run the chosen strategy; every one falls back to heuristic on failure. */
+    async classify(strategy, input, candidates) {
+        if (strategy === "jev" && this.deps.decide) {
+            try {
+                // classifyJev is already fail-open internally; this guards the rest.
+                return await classifyJev(input, this.deps.decide, this.config.timeoutMs, candidates, {
+                    upgrade: this.config.minUpgradeConfidence,
+                    downgrade: this.config.minDowngradeConfidence,
+                });
+            }
+            catch (err) {
+                this.deps.logger?.warn?.("[ClassifierRouter] Jev classify failed — using heuristic", { error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        if (strategy === "llm" && this.deps.generate) {
             try {
                 return await classifyLlm(input, this.deps.generate, this.config.classifierModel, this.config.timeoutMs, candidates);
             }
@@ -90,25 +179,29 @@ export class ClassifierRouter {
      * pick a model directly. Works for ANY pool, registry-backed or not.
      */
     buildCandidates() {
-        const pool = this.config.pool ?? [];
+        // Candidates are built BEFORE classification, so they are scored against
+        // the neutral tier. The rendered description a model sees does not depend
+        // on difficulty anyway — it is a statement of the model's properties — and
+        // the deterministic fallback re-scores against the real tier once known.
+        this.registryIndex ??= buildRegistryIndex();
         const byId = new Map();
         const used = new Set();
         const descriptors = [];
-        pool.forEach((m, i) => {
+        this.pool.forEach((m, i) => {
             let id = m.id ?? (m.model ? `${m.provider}/${m.model}` : m.provider);
             if (used.has(id)) {
                 id = `${id}#${i}`;
             }
             used.add(id);
             byId.set(id, m);
-            descriptors.push({
-                id,
-                provider: m.provider,
-                model: m.model,
-                description: m.description,
-                tiers: m.tiers,
-                capabilities: this.metaFor(m).capabilities,
-            });
+            const candidate = enrichCandidate(id, m, "moderate", this.registryIndex);
+            // A host-declared capability list wins over the registry's, matching
+            // metaFor's precedence.
+            candidate.capabilities =
+                m.capabilities ??
+                    candidate.capabilities ??
+                    this.metaFor(m).capabilities;
+            descriptors.push(candidate);
         });
         return { descriptors, byId };
     }
@@ -117,28 +210,114 @@ export class ClassifierRouter {
      * (`selectedModelId`); otherwise falls back to difficulty-based tierMap /
      * metadata scoring.
      */
-    selectModels(decision, byId) {
-        if (decision.selectedModelId && byId) {
-            const picked = byId.get(decision.selectedModelId);
-            if (picked) {
-                const rest = (this.config.pool ?? []).filter((m) => m !== picked);
-                const rankedRest = this.rank(this.filterByCapabilities(rest, decision.requiredCapabilities), decision.difficulty);
-                return [picked, ...rankedRest];
+    selectModels(decision, input, byId) {
+        const tierRanked = this.rankForDifficulty(decision, input);
+        const picked = decision.selectedModelId && byId
+            ? byId.get(decision.selectedModelId)
+            : undefined;
+        if (picked) {
+            // A pick that cannot hold the request is vetoed outright, whatever the
+            // confidence. That failure is not a degraded answer but a hard provider
+            // error, which ModelPool records as a permanent cooldown.
+            if (!this.fitsRequest(picked, input)) {
+                this.deps.logger?.debug?.("[ClassifierRouter] classifier pick dropped — window too small", {
+                    id: decision.selectedModelId,
+                    estimatedInputTokens: input.estimatedInputTokens,
+                });
+            }
+            else if (this.pickClearsBar(decision, picked, tierRanked[0])) {
+                return [picked, ...tierRanked.filter((m) => m !== picked)];
+            }
+            else {
+                this.deps.logger?.debug?.("[ClassifierRouter] classifier pick dropped — below its bar", {
+                    id: decision.selectedModelId,
+                    confidence: decision.selectedModelConfidence,
+                });
             }
         }
+        return tierRanked;
+    }
+    /**
+     * Whether a directly-picked model clears the bar that applies to it.
+     *
+     * The bars are asymmetric because the two mistakes do not cost the same, and
+     * which one a pick risks depends on what the difficulty tier would otherwise
+     * have chosen. Picking something COSTLIER than the tier's own choice risks
+     * spending more than necessary, so it clears the low upgrade bar. Picking
+     * something CHEAPER risks handing the task to a model that cannot do it, so
+     * it must clear the high downgrade bar. Agreeing with the tier needs no bar
+     * at all.
+     *
+     * A strategy that reports no confidence for its pick — the LLM classifier —
+     * is honoured exactly as before. Its self-reported numbers are not
+     * calibrated, so a bar over them would be arithmetic on noise, and imposing
+     * one would silently change the behaviour of a shipped, unrelated strategy.
+     */
+    pickClearsBar(decision, picked, tierTop) {
+        const confidence = decision.selectedModelConfidence;
+        if (confidence === undefined || !tierTop || picked === tierTop) {
+            return true;
+        }
+        const pickedCost = this.metaFor(picked).cost ?? NEUTRAL;
+        const topCost = this.metaFor(tierTop).cost ?? NEUTRAL;
+        const bar = pickedCost < topCost
+            ? (this.config.minDowngradeConfidence ?? 0.6)
+            : (this.config.minUpgradeConfidence ?? 0.3);
+        return confidence >= bar;
+    }
+    /** The difficulty-based ranking, independent of any direct pick. */
+    rankForDifficulty(decision, input) {
         const eligible = this.candidatesFor(decision);
-        const capable = this.filterByCapabilities(eligible, decision.requiredCapabilities);
+        const capable = this.withRoomFor(this.filterByCapabilities(eligible, decision.requiredCapabilities), input);
+        // With the catalogue on there is no hand-declared ordering to respect and
+        // far more members than a host would ever write out, so ranking uses the
+        // registry's use-case scores. Without it, the long-standing cost/quality
+        // comparator stands — a declared pool's behaviour is unchanged.
+        if (this.config.catalog?.enabled) {
+            this.registryIndex ??= buildRegistryIndex();
+            const index = this.registryIndex;
+            const enriched = capable.map((m, i) => enrichCandidate(m.id ?? (m.model ? `${m.provider}/${m.model}` : `${m.provider}#${i}`), m, decision.difficulty, index));
+            const order = rankCatalogue(enriched, decision.difficulty, input, decision.requiredCapabilities);
+            const byCandidateId = new Map(capable.map((m, i) => [
+                m.id ?? (m.model ? `${m.provider}/${m.model}` : `${m.provider}#${i}`),
+                m,
+            ]));
+            const ranked = order
+                .map((c) => byCandidateId.get(c.id))
+                .filter((m) => m !== undefined);
+            if (ranked.length > 0) {
+                return ranked;
+            }
+        }
         return this.rank(capable, decision.difficulty);
     }
+    /**
+     * Whether a member's context window can hold the estimated request. Unknown
+     * windows pass — the registry does not know every model, and starving the
+     * pool on missing metadata is worse than an occasional retry.
+     */
+    fitsRequest(member, input) {
+        const needed = input.estimatedInputTokens ?? 0;
+        if (needed <= 0 || !member.model) {
+            return true;
+        }
+        this.registryIndex ??= buildRegistryIndex();
+        const info = this.registryIndex.get(member.model);
+        return !info || info.limits.maxContextTokens >= needed;
+    }
+    /** Drop members too small for the request, unless that empties the pool. */
+    withRoomFor(members, input) {
+        const kept = members.filter((m) => this.fitsRequest(m, input));
+        return kept.length > 0 ? kept : members;
+    }
     /** Candidate members for a difficulty: explicit tierMap or eligible pool. */
     candidatesFor(decision) {
         const tierMembers = this.config.tierMap?.[decision.difficulty];
         if (tierMembers && tierMembers.length > 0) {
             return tierMembers;
         }
-        const pool = this.config.pool ?? [];
-        const eligible = pool.filter((m) => !m.tiers || m.tiers.includes(decision.difficulty));
-        return eligible.length > 0 ? eligible : pool;
+        const eligible = this.pool.filter((m) => !m.tiers || m.tiers.includes(decision.difficulty));
+        return eligible.length > 0 ? eligible : this.pool;
     }
     /** Drop members that cannot satisfy the required capabilities (lenient). */
     filterByCapabilities(members, required) {
@@ -197,6 +376,27 @@ export class ClassifierRouter {
         // documented weight contract that a plain append would silently drop.
         return [...sortMeasured(measured), ...sortMeasured(unmeasured)];
     }
+    /**
+     * Turn the classifier's context reading into a compaction threshold.
+     *
+     * Returns undefined — meaning "leave the 0.8 default alone" — whenever the
+     * feature is off, no scope was read, or the scope is the widest one. The
+     * mapping can only ever LOWER the threshold, which is enforced in
+     * `contextScopeToThreshold` rather than here, because the consequence of
+     * getting it wrong in the other direction is not recoverable: a
+     * `context_window` error puts the model into ModelPool's 10-year cooldown.
+     */
+    selectContextBudget(decision) {
+        if (this.config.contextBudget === false || !decision.contextScope) {
+            return undefined;
+        }
+        const index = CLASSIFIER_CONTEXT_SCOPES.indexOf(decision.contextScope);
+        if (index < 0) {
+            return undefined;
+        }
+        const threshold = contextScopeToThreshold(index);
+        return threshold < 0.8 ? threshold : undefined;
+    }
     /** Tool narrowing: per-difficulty directive, then classifier hints. */
     selectTools(decision) {
         const directive = this.config.toolDirectives?.[decision.difficulty];

package/dist/routing/classifierStrategies.d.ts

@@ -6,8 +6,12 @@
  * - `classifyLlm` — runs a cheap "classifier model" via an injected generate
  *   function, asking for a schema-constrained difficulty verdict. Falls back to
  *   the heuristic on any failure.
+ * - `classifyJev` — one round trip to a decision model, which answers
+ *   difficulty, capabilities, risk and model choice *simultaneously* and
+ *   reports a calibrated confidence. Falls back to the heuristic on any
+ *   failure or when the verdict is not confident enough to act on.
  */
-import type { ClassifierCandidate, ClassifierDecision, ClassifierDifficulty, ClassifierGenerateFn, ClassifierModelRef, ClassifierRouterInput } from "../types/index.js";
+import type { ClassifierCandidate, ClassifierContextScope, ClassifierDecideFn, ClassifierDecision, ClassifierDifficulty, ClassifierGenerateFn, ClassifierModelRef, ClassifierRouterInput } from "../types/index.js";
 /** Difficulty tiers, ordered easiest → hardest. */
 export declare const CLASSIFIER_DIFFICULTIES: ClassifierDifficulty[];
 /**
@@ -21,3 +25,31 @@ export declare function classifyHeuristic(input: ClassifierRouterInput): Classif
  * returns output that does not match the schema.
  */
 export declare function classifyLlm(input: ClassifierRouterInput, generate: ClassifierGenerateFn, classifierModel?: ClassifierModelRef, timeoutMs?: number, candidates?: ClassifierCandidate[]): Promise<ClassifierDecision>;
+/**
+ * How much context the request needs, narrowest → widest. Ordered, because a
+ * decision model places things on a scale reliably and names numbers badly:
+ * asking "how many tokens" would get digits read as text, while asking "which
+ * of these four descriptions fits" gets a calibrated position.
+ */
+export declare const CLASSIFIER_CONTEXT_SCOPES: ClassifierContextScope[];
+/**
+ * Map a score answer onto a compaction threshold, clamped so it can only ever
+ * lower the default.
+ */
+export declare function contextScopeToThreshold(index: number): number;
+/**
+ * Decision-model classifier — one request answers difficulty, capabilities,
+ * risk and model selection at once.
+ *
+ * Latency is flat in question count (1 question ~393ms, 400 ~465ms), so the
+ * capability questions are effectively free and are asked speculatively even
+ * when nothing downstream may need them. This is the opposite of the LLM
+ * strategy's economics, where every extra field costs output tokens.
+ *
+ * Returns the heuristic verdict — never throws — when no decision provider is
+ * configured, the call fails, or the answer is not confident enough to act on.
+ */
+export declare function classifyJev(input: ClassifierRouterInput, decide: ClassifierDecideFn, timeoutMs?: number, candidates?: ClassifierCandidate[], thresholds?: {
+    upgrade?: number;
+    downgrade?: number;
+}): Promise<ClassifierDecision>;

package/dist/routing/classifierStrategies.js

@@ -6,10 +6,16 @@
  * - `classifyLlm` — runs a cheap "classifier model" via an injected generate
  *   function, asking for a schema-constrained difficulty verdict. Falls back to
  *   the heuristic on any failure.
+ * - `classifyJev` — one round trip to a decision model, which answers
+ *   difficulty, capabilities, risk and model choice *simultaneously* and
+ *   reports a calibrated confidence. Falls back to the heuristic on any
+ *   failure or when the verdict is not confident enough to act on.
  */
 import { z } from "zod";
 import { analyzePrompt, calculateConfidence, } from "../utils/taskClassificationUtils.js";
 import { withTimeout } from "../utils/async/index.js";
+import { decisionBooleanConfidence, readDecisionBoolean, readDecisionChoice, readDecisionScore, } from "../utils/decisionAnswers.js";
+import { renderCandidate } from "./modelCatalog.js";
 /** Difficulty tiers, ordered easiest → hardest. */
 export const CLASSIFIER_DIFFICULTIES = [
     "trivial",
@@ -153,3 +159,234 @@ export async function classifyLlm(input, generate, classifierModel, timeoutMs, c
         reason: d.reason ?? "llm classifier",
     };
 }
+/**
+ * Rubric handed to the decision model, ordered easiest → hardest. Deliberately
+ * about the shape of the work, not about model names: the model never sees a
+ * provider or model id, and this file maps its judgement onto the pool.
+ */
+const JEV_DIFFICULTY_CRITERIA = {
+    trivial: "Mechanical and local: rename a symbol, fix a typo, add an import, run one named command, or answer something already stated in the request.",
+    simple: "A small localised change or a direct factual answer. One file, one obvious approach.",
+    moderate: "Ordinary engineering: implement a well-specified change across a few files, write tests, fix a clearly described bug, review a small diff.",
+    hard: "Deep reasoning: architecture and design, debugging a failure whose cause is unknown, security analysis, concurrency, refactors spanning several systems.",
+    expert: "Frontier-level work: ambiguous requirements, novel design with no established pattern, or analysis where a wrong answer is costly and hard to detect.",
+};
+/**
+ * Asked about the ACT, not the subject.
+ *
+ * This wording matters more than it looks. The obvious phrasing — "the task
+ * touches production, money or credentials" — scores very high on ordinary
+ * code that merely *concerns* those things ("add a refund endpoint that calls
+ * Stripe"), and escalates every such request to the most expensive model. The
+ * second sentence is what separates writing the code from running it.
+ */
+const JEV_RISK_INSTRUCTIONS = "Carrying out this request would itself change production, move real money, expose credentials, or alter data that cannot be restored. Writing or testing code that deals with such things, without running it against the real system, does not count.";
+/** Above this, risk overrides the tier and skips the confidence thresholds. */
+const JEV_RISK_FORCE_THRESHOLD = 0.7;
+/**
+ * How much context the request needs, narrowest → widest. Ordered, because a
+ * decision model places things on a scale reliably and names numbers badly:
+ * asking "how many tokens" would get digits read as text, while asking "which
+ * of these four descriptions fits" gets a calibrated position.
+ */
+export const CLASSIFIER_CONTEXT_SCOPES = [
+    "current-message",
+    "recent-turns",
+    "full-conversation",
+    "everything",
+];
+const JEV_CONTEXT_CRITERIA = [
+    "Self-contained. Everything needed to answer is in the request itself; earlier conversation would not change the answer.",
+    "Needs the last few exchanges — a follow-up, a correction, or a reference to something just discussed.",
+    "Needs the whole conversation, including decisions and constraints established much earlier.",
+    "Needs the conversation and every document, file and tool result that has been gathered.",
+];
+/**
+ * Compaction thresholds per context scope, indexed to match
+ * {@link CLASSIFIER_CONTEXT_SCOPES}.
+ *
+ * Every one is at or below the 0.8 default, and that is a hard invariant
+ * rather than a tuning choice. Raising a budget lets a request through that
+ * the model then rejects for exceeding its window — and `ModelPool` treats a
+ * `context_window` error as a PERMANENT cooldown (10 years), so one
+ * optimistic guess retires that model for the life of the process. Shrinking
+ * a budget merely compacts a little earlier than it had to.
+ */
+const CONTEXT_SCOPE_THRESHOLD = [0.45, 0.6, 0.75, 0.8];
+/** Below this calibrated confidence the scope reading is ignored entirely. */
+const MIN_CONTEXT_SCOPE_CONFIDENCE = 0.5;
+/** The default the budget checker uses when nobody passes a threshold. */
+const DEFAULT_COMPACTION_THRESHOLD = 0.8;
+/**
+ * Map a score answer onto a compaction threshold, clamped so it can only ever
+ * lower the default.
+ */
+export function contextScopeToThreshold(index) {
+    const clamped = Math.max(0, Math.min(CONTEXT_SCOPE_THRESHOLD.length - 1, Math.round(index)));
+    return Math.min(DEFAULT_COMPACTION_THRESHOLD, CONTEXT_SCOPE_THRESHOLD[clamped] ?? DEFAULT_COMPACTION_THRESHOLD);
+}
+/**
+ * Default confidence bars. They differ because the two mistakes do not cost
+ * the same: routing a simple task to an expensive model wastes money, while
+ * routing a hard task to a weak one produces a wrong answer.
+ */
+const DEFAULT_MIN_UPGRADE_CONFIDENCE = 0.3;
+const DEFAULT_MIN_DOWNGRADE_CONFIDENCE = 0.6;
+/** The neutral tier a verdict is judged as moving up or down from. */
+const NEUTRAL_DIFFICULTY_INDEX = CLASSIFIER_DIFFICULTIES.indexOf("moderate");
+/** Narrow an arbitrary option name back onto the difficulty union. */
+function isClassifierDifficulty(value) {
+    return CLASSIFIER_DIFFICULTIES.includes(value);
+}
+/**
+ * Decision-model classifier — one request answers difficulty, capabilities,
+ * risk and model selection at once.
+ *
+ * Latency is flat in question count (1 question ~393ms, 400 ~465ms), so the
+ * capability questions are effectively free and are asked speculatively even
+ * when nothing downstream may need them. This is the opposite of the LLM
+ * strategy's economics, where every extra field costs output tokens.
+ *
+ * Returns the heuristic verdict — never throws — when no decision provider is
+ * configured, the call fails, or the answer is not confident enough to act on.
+ */
+export async function classifyJev(input, decide, timeoutMs, candidates, thresholds) {
+    const minUpgrade = thresholds?.upgrade ?? DEFAULT_MIN_UPGRADE_CONFIDENCE;
+    const minDowngrade = thresholds?.downgrade ?? DEFAULT_MIN_DOWNGRADE_CONFIDENCE;
+    const questions = {
+        difficulty: {
+            type: "choice",
+            instructions: "What kind of work does this request require from an AI coding assistant? Judge by reasoning depth, number of steps, domain expertise, and ambiguity.",
+            criteria: JEV_DIFFICULTY_CRITERIA,
+        },
+        needs_vision: {
+            type: "boolean",
+            instructions: "Does answering this request require looking at an image, screenshot, diagram, or PDF page?",
+        },
+        needs_tools: {
+            type: "boolean",
+            instructions: "Does this request require running commands, reading or writing files, or calling external services — as opposed to being answerable from the text alone?",
+        },
+        needs_reasoning: {
+            type: "boolean",
+            instructions: "Does this request require sustained multi-step reasoning before a correct answer can be given?",
+        },
+        risky: { type: "boolean", instructions: JEV_RISK_INSTRUCTIONS },
+        context: {
+            type: "score",
+            instructions: "How much of the earlier conversation does answering this request actually require?",
+            criteria: JEV_CONTEXT_CRITERIA,
+        },
+    };
+    // Only ask the model-selection question when there is a pool to choose
+    // from; a choice over fewer than two options carries no information.
+    const byId = new Map((candidates ?? []).map((c) => [c.id, c]));
+    if (byId.size > 1) {
+        questions.model = {
+            type: "choice",
+            instructions: "Which of these models is the cheapest one that can still complete this request correctly? A model whose context window cannot hold the request is never the right answer.",
+            criteria: Object.fromEntries(Array.from(byId.values()).map((c) => [
+                c.id,
+                renderCandidate(c) || null,
+            ])),
+        };
+    }
+    // Structured state: the decision API accepts JSON, and the extra signals
+    // are already assembled by the caller. Sending them costs almost nothing
+    // and they are exactly what distinguishes a long tool-using request from a
+    // short conversational one.
+    const result = await decide({
+        state: {
+            request: (input.prompt ?? "").slice(0, 8000),
+            estimated_input_tokens: input.estimatedInputTokens ?? 0,
+            has_tools_available: input.hasTools ?? false,
+            request_includes_images: input.requiresVision ?? false,
+            caller_requested_thinking: input.thinkingLevel ?? "none",
+        },
+        questions,
+        timeoutMs,
+    });
+    if (!result) {
+        return classifyHeuristic(input);
+    }
+    // Read first, and keep it separate from everything below. The context
+    // judgement is independent of the tier — a trivial request can still depend
+    // on the whole conversation, and an expert one can be entirely
+    // self-contained — so it is gated on its own calibrated confidence and
+    // survives every path on which the difficulty verdict is discarded.
+    const contextReading = readDecisionScore(result.answers, "context");
+    const contextScope = contextReading && contextReading.confidence >= MIN_CONTEXT_SCOPE_CONFIDENCE
+        ? CLASSIFIER_CONTEXT_SCOPES[Math.max(0, Math.min(CLASSIFIER_CONTEXT_SCOPES.length - 1, Math.round(contextReading.score)))]
+        : undefined;
+    const withContext = (decision) => contextScope
+        ? {
+            ...decision,
+            contextScope,
+            contextScopeConfidence: contextReading?.confidence,
+        }
+        : decision;
+    const difficulty = readDecisionChoice(result.answers, "difficulty");
+    if (!difficulty || !isClassifierDifficulty(difficulty.choice)) {
+        return withContext(classifyHeuristic(input));
+    }
+    // Risk overrides the tier outright and skips the confidence bars — this is
+    // the one case that is not a confidence question. It may only ever RAISE
+    // the tier, never lower one.
+    const risk = readDecisionBoolean(result.answers, "risky") ?? 0;
+    const forcedByRisk = risk > JEV_RISK_FORCE_THRESHOLD;
+    const wantedIndex = CLASSIFIER_DIFFICULTIES.indexOf(difficulty.choice);
+    const effectiveIndex = forcedByRisk
+        ? Math.max(wantedIndex, CLASSIFIER_DIFFICULTIES.indexOf("hard"))
+        : wantedIndex;
+    // Asymmetric gate: a verdict harder than neutral spends more, so it clears
+    // the low bar; one easier than neutral spends less, so it clears the high
+    // bar. Below the applicable bar the heuristic stands.
+    if (!forcedByRisk) {
+        const isDowngrade = effectiveIndex < NEUTRAL_DIFFICULTY_INDEX;
+        const bar = isDowngrade ? minDowngrade : minUpgrade;
+        if (difficulty.confidence < bar) {
+            const fallback = classifyHeuristic(input);
+            return withContext({
+                ...fallback,
+                reason: `jev: ${difficulty.choice} @ ${difficulty.confidence.toFixed(2)} below the ${isDowngrade ? "downgrade" : "upgrade"} bar ${bar} — ${fallback.reason}`,
+            });
+        }
+    }
+    const capabilities = new Set();
+    // A yes/no answer carries no confidence of its own, so require it to be
+    // clearly on one side of the coin flip before acting on it.
+    const capabilityFor = {
+        needs_vision: "vision",
+        needs_tools: "tools",
+        needs_reasoning: "reasoning",
+    };
+    for (const [id, tag] of Object.entries(capabilityFor)) {
+        const probability = readDecisionBoolean(result.answers, id);
+        if (probability !== undefined &&
+            probability > 0.5 &&
+            decisionBooleanConfidence(probability) >= 0.4) {
+            capabilities.add(tag);
+        }
+    }
+    // The pick is reported WITHOUT a confidence gate here on purpose. Whether a
+    // given pick is an upgrade or a downgrade depends on what the difficulty
+    // tier would otherwise have chosen, and only the router knows that — so the
+    // asymmetric bars are applied there. Gating on the upgrade bar at this point
+    // treated every pick as an upgrade, which let a low-confidence pick route a
+    // hard task DOWN to a cheap model on a bar meant for the opposite case.
+    const picked = readDecisionChoice(result.answers, "model");
+    const selectedModelId = picked && byId.has(picked.choice) ? picked.choice : undefined;
+    const chosen = CLASSIFIER_DIFFICULTIES[effectiveIndex];
+    return {
+        difficulty: chosen,
+        confidence: difficulty.confidence,
+        requiredCapabilities: withRequestCapabilities(input, Array.from(capabilities)),
+        selectedModelId,
+        selectedModelConfidence: selectedModelId ? picked?.confidence : undefined,
+        contextScope,
+        contextScopeConfidence: contextReading?.confidence,
+        reason: forcedByRisk
+            ? `jev(${result.model}): ${chosen}, forced by risk ${risk.toFixed(2)} in ${result.latencyMs}ms`
+            : `jev(${result.model}): ${chosen} @ ${difficulty.confidence.toFixed(2)} in ${result.latencyMs}ms`,
+    };
+}

package/dist/routing/index.d.ts

@@ -6,4 +6,4 @@
 export { classifyProviderError, ModelPool } from "./modelPool.js";
 export { createDefaultRequestRouter } from "./requestRouter.js";
 export { ClassifierRouter } from "./classifierRouter.js";
-export { classifyHeuristic, classifyLlm } from "./classifierStrategies.js";
+export { classifyHeuristic, classifyJev, classifyLlm, } from "./classifierStrategies.js";

package/dist/routing/index.js

@@ -6,4 +6,4 @@
 export { classifyProviderError, ModelPool } from "./modelPool.js";
 export { createDefaultRequestRouter } from "./requestRouter.js";
 export { ClassifierRouter } from "./classifierRouter.js";
-export { classifyHeuristic, classifyLlm } from "./classifierStrategies.js";
+export { classifyHeuristic, classifyJev, classifyLlm, } from "./classifierStrategies.js";