agent-nuvira 3.3.13 → 3.3.15

package/dist/cli/model.js

@@ -25,16 +25,26 @@ import inquirer from 'inquirer';
 import { resolveNuviraHome } from '../config/paths.js';
 import { BaseCommand } from './commands.js';
 import { showModelPicker } from './model-picker.js';
+import { CATALOG_PROVIDER_IDS } from '../inference/provider-catalog.js';
 import { getPluginRegistry } from '../plugins/registry.js';
 import { recommendModel } from '../learning/model-router.js';
 import { getModelBadge } from '../inference/model-catalog.js';
 import { getHybridRouter } from '../learning/hybrid-router.js';
 import { AUTO_MODEL, AUTO_PROVIDER, getAutoRouter, isAutoModel, isAutoProvider, PIIPolicyError, GovernancePolicyError, } from '../learning/auto-router.js';
 import { buildAutoResolveOptions } from '../learning/resolve-options.js';
+import { parseRequestSync } from '../nlu/parser.js';
+import { resolveDispatch } from '../nlu/actions.js';
 import { recordRoutingDecision, getExplainSnapshots } from '../learning/routing-history.js';
 import { diffRoutingDecisions, formatDecisionDiff } from '../learning/decision-diff.js';
 import { getRouterBandit, COMPLEXITY_BUCKETS, } from '../learning/router-bandit.js';
 import { getQuotaLedger } from '../learning/quota-ledger.js';
+import { getModelRegistry } from '../learning/model-registry.js';
+import { ENTITLEMENT_LABEL, areTwins, classifyPairEntitlement, entitlementNote, } from '../learning/pair-entitlement.js';
+import { identityKey, identityProvenance } from '../learning/model-identity.js';
+import { DEFAULT_PRIORS, capabilityLines, deriveTier, effectiveParameter, } from '../learning/capability-evidence.js';
+import { externalPriorsFor } from '../learning/catalog-feed.js';
+import { acceptanceSummary, formatAcceptanceSummary } from '../learning/acceptance-model.js';
+import { getProviderFallback } from '../learning/provider-fallback.js';
 import { getRouterPromotion, DEFAULT_MIN_PROMOTION_DECISIONS, } from '../learning/router-promotion.js';
 import { getMlRouter } from '../learning/ml-router.js';
 import { logger } from '../utils/logger.js';
@@ -124,6 +134,17 @@ const EXPLAIN_SAMPLES = [
     { label: '🟠 complex', task: 'design a distributed event-driven microservices architecture' },
     { label: '🔴 critical', task: 'deploy to production with zero downtime' },
 ];
+/** Repeatable `--exclude-provider <provider>` collector. */
+function collectProvider(value, previous) {
+    previous.push(value);
+    return previous;
+}
+/**
+ * A session failure sinks a provider by scoring exactly like a live cooldown
+ * (`circuitBreakerStatus`). Any positive value parks it, so this is not a real
+ * duration — it says "this provider is out for this decision".
+ */
+const SESSION_EXCLUDE_COOLDOWN_MS = 60_000;
 // ─── ModelCommand ───────────────────────────────────────────────────────────
 export class ModelCommand extends BaseCommand {
     create() {
@@ -159,7 +180,15 @@ export class ModelCommand extends BaseCommand {
             .option('-a, --agent <type>', 'Agent type to route for (default: chat)', 'chat')
             .option('-j, --json', 'Output as JSON (for scripting and CI)', false)
             .option('--since <ref>', 'P3-M3.3: diff against a previous decision — an explain id, @n (nth most recent explain), or an epoch-ms timestamp', undefined)
-            .action((task, opts) => this.showExplain(task, opts));
+            .option('--context-tokens <n>', 'Item 14: the prompt token count the runtime would have seen (context preflight basis) — reproduce a decision made with a large history', undefined)
+            .option('--exclude-provider <provider>', 'Item 14: a provider already failed THIS SESSION, repeatable — it sinks by scoring exactly as the runtime excludes it', collectProvider, [])
+            .action((task, opts) => this.showExplain(task, {
+            agent: opts.agent,
+            json: opts.json,
+            since: opts.since,
+            contextTokens: opts.contextTokens !== undefined ? Number(opts.contextTokens) : undefined,
+            excludeProviders: opts.excludeProvider,
+        }));
         cmd
             .command('health')
             .description('Quick health check for the currently active provider')
@@ -197,7 +226,33 @@ export class ModelCommand extends BaseCommand {
     }
     // ── Subcommand: list ───────────────────────────────────────────────────
     async listProviders(opts) {
-        const builtinTypes = ['local', 'groq', 'nim', 'gemini', 'openrouter'];
+        /**
+         * The provider set the ROUTER uses — not a hand-written list of five.
+         *
+         * `rankAvailableProviders` (the router's source of truth) builds its candidate
+         * set from the catalog PLUS whatever the user configured. A literal array here
+         * made `model list` disagree with routing about which providers even exist:
+         * measured live, a machine whose turns were served by `deepseek` — with the
+         * debug header and the trace both naming it — printed only
+         * local/groq/nim/gemini/openrouter, so `deepseek` (and every other catalog
+         * provider: bedrock, openai, mistral, …) was invisible in the one command whose
+         * whole job is "what can I use?". One source, one inventory.
+         *
+         * The familiar five keep their place at the top so the table does not reorder
+         * itself for existing users; the rest follow in catalog order.
+         */
+        const builtinTypes = (() => {
+            const preferred = ['local', 'groq', 'nim', 'gemini', 'openrouter'];
+            let configured = [];
+            try {
+                configured = Object.keys(this.configManager.getAll().providers ?? {});
+            }
+            catch {
+                // Best-effort — an unreadable config must not empty the table.
+            }
+            const all = new Set([...preferred, ...CATALOG_PROVIDER_IDS, ...configured]);
+            return [...all];
+        })();
         const registry = getPluginRegistry();
         const pluginTypes = registry.getAllPlugins().map((p) => p.getProviderType());
         const active = readActiveModelState();
@@ -291,7 +346,14 @@ export class ModelCommand extends BaseCommand {
         console.log('  ┌──────────────────────────────────┬──────────┬──────────┬──────────────────┐');
         console.log('  │ Provider                         │ Status   │ Available│ Model            │');
         console.log('  ├──────────────────────────────────┼──────────┼──────────┼──────────────────┤');
-        for (const r of results) {
+        // Usable first. The table now carries the WHOLE catalog (so it agrees with
+        // routing), which means most rows are providers this machine has no key for.
+        // Putting the callable ones on top keeps the answer to "what can I use?" in
+        // the first few lines rather than below a dozen `Needs key` rows. Stable
+        // sort, so the familiar five keep their relative order.
+        const rankOf = (r) => r.available ? 0 : r.configured ? 1 : 2;
+        const ordered = [...results].sort((a, b) => rankOf(a) - rankOf(b));
+        for (const r of ordered) {
             const name = `${r.icon} ${r.label}`.padEnd(30).slice(0, 30);
             const status = r.isActive ? '✅ Active' : r.configured ? '⚙️  Ready' : '⏳ Needs key';
             const avail = r.available ? '✅' : '⛔';
@@ -304,6 +366,45 @@ export class ModelCommand extends BaseCommand {
             logger.success(`Active: ${active.provider}/${active.model}`);
             console.log(`  (set ${new Date(active.updatedAt).toLocaleString()})`);
         }
+        // ── A1: the SAME model, opposite verdicts ──────────────────────────────
+        // Two rows for one model can disagree completely (`openrouter` refuses a
+        // model `deepseek` serves), and the table above shows only each provider's own
+        // default — so the pair was invisible. Print only the groups whose verdicts
+        // genuinely DISAGREE: same identity, different answer about whether it can be
+        // called. Each verdict is read from its own row (identity groups capability
+        // and legibility, never availability).
+        try {
+            const registry = getModelRegistry();
+            const rows = registry.getTrackedProviders().flatMap((p) => registry.getAllModelsForProvider(p));
+            const groups = new Map();
+            for (const r of rows) {
+                const key = identityKey(r.model);
+                if (!key)
+                    continue;
+                const list = groups.get(key);
+                if (list)
+                    list.push(r);
+                else
+                    groups.set(key, [r]);
+            }
+            const mixed = [...groups.values()].filter((g) => new Set(g.map((r) => classifyPairEntitlement(r))).size > 1);
+            if (mixed.length > 0) {
+                console.log('');
+                logger.highlight('  ── The same model, different verdicts (A1) ──');
+                for (const g of mixed.slice(0, 5)) {
+                    console.log(`   ${g[0].model}`);
+                    for (const r of g) {
+                        const e = classifyPairEntitlement(r);
+                        console.log(`     ${ENTITLEMENT_LABEL[e]} ${r.provider} — ${entitlementNote(e, r)}`);
+                    }
+                }
+                if (mixed.length > 5)
+                    console.log(`   … and ${mixed.length - 5} more.`);
+            }
+        }
+        catch {
+            // Best-effort — this section must never break `model list`.
+        }
         console.log('');
         logger.info('Run `nuvira model switch` to change the active provider/model.');
         logger.info('Run `nuvira doctor` for full diagnostic checks.');
@@ -505,9 +606,13 @@ export class ModelCommand extends BaseCommand {
     showExplain(task, opts) {
         const router = getAutoRouter();
         const agentType = opts.agent || 'chat';
+        const runtime = {
+            contextTokens: opts.contextTokens,
+            excludeProviders: opts.excludeProviders,
+        };
         if (opts.json) {
             try {
-                console.log(JSON.stringify(this.buildExplainJSON(router, agentType, task, opts.since), null, 2));
+                console.log(JSON.stringify(this.buildExplainJSON(router, agentType, task, opts.since, runtime), null, 2));
             }
             catch (err) {
                 // A PII/governance policy block must not crash the JSON contract —
@@ -526,6 +631,14 @@ export class ModelCommand extends BaseCommand {
         console.log('');
         logger.highlight('═══  Auto Model Routing — Explain  ═══');
         console.log('');
+        // Item 14 — say plainly what this decision could NOT see, so an offline
+        // answer is never read as the live one. `explain` has no session: a
+        // continuation's routing text and the session's failed-provider set exist
+        // only at runtime, and both change the pick.
+        logger.info(`Runtime inputs: context ${runtime.contextTokens !== undefined ? `~${runtime.contextTokens} tokens` : '(estimated from the task)'} · ` +
+            `excluded providers: ${runtime.excludeProviders?.length ? runtime.excludeProviders.join(', ') : 'none'}`);
+        logger.info('A live session also carries its own failed-provider set; pass --exclude-provider to reproduce it, and --context-tokens to match a large history.');
+        console.log('');
         if (task) {
             logger.info(`Task: "${task}"  ·  Agent: ${agentType}`);
             console.log('');
@@ -533,10 +646,10 @@ export class ModelCommand extends BaseCommand {
                 // P3-M3.3: `--since <ref>` renders a before → after diff against a
                 // previous explain snapshot instead of the full decision view.
                 if (opts.since) {
-                    this.renderRoutingDecisionDiff(router, agentType, task, opts.since);
+                    this.renderRoutingDecisionDiff(router, agentType, task, opts.since, runtime);
                 }
                 else {
-                    this.renderRoutingDecision(router, agentType, task);
+                    this.renderRoutingDecision(router, agentType, task, false, runtime);
                 }
             }
             catch (err) {
@@ -560,7 +673,7 @@ export class ModelCommand extends BaseCommand {
         for (const s of EXPLAIN_SAMPLES) {
             logger.highlight(`  ${s.label} — "${s.task}"`);
             try {
-                this.renderRoutingDecision(router, agentType, s.task, true);
+                this.renderRoutingDecision(router, agentType, s.task, true, runtime);
             }
             catch (err) {
                 // A single sample that violates a PII/governance policy renders the
@@ -599,9 +712,9 @@ export class ModelCommand extends BaseCommand {
      * Single task → one decision object; no task → all 5 sample complexities.
      * Includes effective per-provider pricing (with override flags).
      */
-    buildExplainJSON(router, agentType, task, since) {
+    buildExplainJSON(router, agentType, task, since, runtime = {}) {
         const toJSON = (t, agent) => {
-            const d = router.resolve(agent, t, buildAutoResolveOptions(this.configManager), this.configManager);
+            const d = this.resolveExplainDecision(router, agent, t, runtime);
             const snapshot = this.buildSnapshot(d);
             // Record the explain snapshot for the dashboard audit trail + usage stats
             // (JSON mode returns early in showExplain, so this is the only hook here)
@@ -678,6 +791,12 @@ export class ModelCommand extends BaseCommand {
                     : undefined,
                 pricing,
                 explanation: d.explanation,
+                // Item 14 — the runtime inputs this decision was reproduced with, so a
+                // script can tell a hypothetical from a reproduced live decision.
+                runtimeInputs: {
+                    contextTokens: runtime.contextTokens,
+                    excludedProviders: runtime.excludeProviders ?? [],
+                },
                 ...(diff ? { diff } : {}),
             };
         };
@@ -688,6 +807,62 @@ export class ModelCommand extends BaseCommand {
             decisions: EXPLAIN_SAMPLES.map((s) => toJSON(s.task, agentType)),
         };
     }
+    /**
+     * D4 — resolve an explain decision through the SAME options the RUNTIME uses.
+     *
+     * `chat.ts` layers two things on top of the shared resolve-options assembly
+     * before calling the router, and `explain` passed neither:
+     *
+     * - `circuitBreakerStatus`, which is what SUNKS a provider sitting in a
+     *   cooling-down circuit breaker. Without it every row looked healthy and
+     *   `explain` could name a provider the runtime would never serve.
+     * - the NLU `taskIntentHint`, which the runtime derives from the same task
+     *   string via `parseRequestSync`/`resolveDispatch` and which overrides the
+     *   profile's intent (e.g. a creative ask), so the two could classify one
+     *   task differently.
+     *
+     * Sharing the assembly is the only way the two can agree: both divergences
+     * were options the explain path never passed. The NLU derivation is
+     * deterministic in the task text, so seeding it here is reproducing the
+     * runtime's assembly, not guessing.
+     */
+    resolveExplainDecision(router, agentType, task, runtime = {}) {
+        let circuitBreakerStatus = [];
+        try {
+            circuitBreakerStatus = getProviderFallback(this.configManager).getCircuitBreakerStatus();
+        }
+        catch {
+            // Best-effort — a breaker read must never break `explain`.
+        }
+        // Item 14 — the session's failed-provider set exists only at runtime, so
+        // `explain` could not see it and could name a provider the session had
+        // already parked. Fold each caller-named exclusion in as an active cooldown:
+        // the router sinks it by scoring, exactly as it sinks a live failure.
+        if (runtime.excludeProviders?.length) {
+            const byProvider = new Map(circuitBreakerStatus.map((c) => [c.provider, c.cooldownRemaining]));
+            for (const p of runtime.excludeProviders) {
+                byProvider.set(p, Math.max(byProvider.get(p) ?? 0, SESSION_EXCLUDE_COOLDOWN_MS));
+            }
+            circuitBreakerStatus = [...byProvider].map(([provider, cooldownRemaining]) => ({ provider, cooldownRemaining }));
+        }
+        // Same NLU seed as the runtime: one parser call on the same text, so an
+        // intent the runtime honours is never invisible to `explain`.
+        let taskIntentHint;
+        try {
+            taskIntentHint = resolveDispatch(parseRequestSync(task)).taskIntentHint;
+        }
+        catch {
+            // Best-effort — a parse failure must never break `explain`.
+        }
+        return router.resolve(agentType, task, {
+            // Item 14 — the context preflight is part of the pickup, so the token
+            // count the runtime saw must reach it; otherwise `explain` estimates
+            // from the task and can name a different provider under a large history.
+            ...buildAutoResolveOptions(this.configManager, { contextHintTokens: runtime.contextTokens }),
+            circuitBreakerStatus,
+            ...(taskIntentHint ? { taskIntentHint } : {}),
+        }, this.configManager);
+    }
     /**
      * Build a RoutingSnapshot from a live decision — the ranked breakdown with
      * dimensions and governance context, persisted with explain decisions so
@@ -750,9 +925,9 @@ export class ModelCommand extends BaseCommand {
      * P3-M3.3: resolve the previous explain decision and render the before →
      * after diff for the current decision (which is also recorded).
      */
-    renderRoutingDecisionDiff(router, agentType, task, ref) {
+    renderRoutingDecisionDiff(router, agentType, task, ref, runtime = {}) {
         const prev = this.resolveExplainRef(ref);
-        const decision = router.resolve(agentType, task, buildAutoResolveOptions(this.configManager), this.configManager);
+        const decision = this.resolveExplainDecision(router, agentType, task, runtime);
         const snapshot = this.buildSnapshot(decision);
         recordRoutingDecision({
             source: 'explain',
@@ -782,8 +957,8 @@ export class ModelCommand extends BaseCommand {
         console.log('');
     }
     /** Render a single routing decision (compact or detailed). */
-    renderRoutingDecision(router, agentType, task, compact = false) {
-        const decision = router.resolve(agentType, task, buildAutoResolveOptions(this.configManager), this.configManager);
+    renderRoutingDecision(router, agentType, task, compact = false, runtime = {}) {
+        const decision = this.resolveExplainDecision(router, agentType, task, runtime);
         // Record the explain snapshot for the dashboard audit trail + usage stats
         recordRoutingDecision({
             source: 'explain',
@@ -809,9 +984,17 @@ export class ModelCommand extends BaseCommand {
         }
         console.log('');
         logger.highlight('  ── Ranked providers ──');
+        // D5 — the list is ordered by AVAILABILITY FIRST (a cooling-down provider
+        // sinks, then a quota-parked one, and only then by score within each group),
+        // because that IS the routing precedence. But only `score` was printed, so a
+        // lower-scored healthy row sitting above a higher-scored cooling one read as
+        // an unsorted list (measured: 0.351, 0.465, 0.397, 0.396). The ranking was
+        // never wrong — the header was silent about the key. State it, so the display
+        // can never appear to contradict the numbers it prints.
+        console.log('   (ordered availability-first — cooling-down, then quota-parked, then score within each group)');
         decision.ranked.forEach((r, i) => {
             const mark = r.provider === decision.provider ? '✅' : '  ';
-            const cd = r.inCooldown ? '  (circuit-breaker cooldown)' : '';
+            const cd = r.inCooldown ? '  (circuit-breaker cooldown)' : r.quotaParked ? '  (quota-parked)' : '';
             const fit = r.capabilityFit !== undefined ? ` 🎯 fit ${Math.round(r.capabilityFit * 100)}%` : '';
             // M2.2/visibility: cost source on EVERY ranked row — 📏 measured (with
             // the real wire-token basis) or 📐 estimated (length-based default).
@@ -833,6 +1016,103 @@ export class ModelCommand extends BaseCommand {
         console.log('');
         logger.success(`  Decision: ${decision.provider}/${decision.model}`);
         console.log(`  ${decision.explanation}`);
+        // D7 — PAIR ENTITLEMENT (2026-10-07). Rank said WHICH model; it never said
+        // whether this ACCOUNT may call it. The reported case was four providers
+        // offering one model where only one key had access — identical ranks, so the
+        // decision was not explainable from the ranking at all. Print the verdict for
+        // the chosen pair, and every same-model twin on another provider with ITS
+        // OWN verdict, so "why this provider and not that one" is answerable from the
+        // output instead of from the registry file. Twins are grouped by the honest
+        // exact/bare-id rule (`areTwins`), and each verdict is read from its own row —
+        // never inherited from a sibling.
+        try {
+            const registry = getModelRegistry();
+            const chosenEntry = registry.getEntry(decision.provider, decision.model);
+            const chosen = classifyPairEntitlement(chosenEntry);
+            const twins = registry
+                .getTrackedProviders()
+                .flatMap((p) => registry.getAllModelsForProvider(p))
+                .filter((e) => e.provider !== decision.provider && areTwins(e.model, decision.model));
+            if (chosen !== 'funded' || twins.length > 0) {
+                console.log('');
+                logger.highlight('  ── Pair entitlement ──');
+                console.log(`   ${ENTITLEMENT_LABEL[chosen]} ${decision.provider}/${decision.model} — ${entitlementNote(chosen, chosenEntry)}`);
+                if (twins.length > 0) {
+                    // WHERE the grouping came from: a declared alias is an assertion, the
+                    // bare-id rule is a derivation, and a reader must be able to tell them
+                    // apart (`learning/model-identity.ts`).
+                    const provenance = identityProvenance(decision.model);
+                    console.log(`   (grouped as the same model${provenance ? ` — ${provenance}` : ' — exact/bare id rule'})`);
+                }
+                for (const t of twins) {
+                    const e = classifyPairEntitlement(t);
+                    console.log(`   ${ENTITLEMENT_LABEL[e]} ${t.provider}/${t.model} — ${entitlementNote(e, t)}`);
+                }
+            }
+        }
+        catch {
+            // Best-effort — an audit section must never break `model explain`.
+        }
+        // Bundle 3b — CAPABILITY BY MEASUREMENT. The scorecard the decision was made
+        // from, in the terms the user asked for: five named parameters, each with its
+        // SAMPLE COUNT, so a number can be weighed instead of trusted. A parameter on
+        // 0 samples is the declared prior by definition (`capability-evidence.ts`),
+        // which is why it is labelled rather than hidden — a bare number with no
+        // basis was the defect, and the same number printed as "prior" is honest.
+        try {
+            const router = getAutoRouter();
+            const registry = getModelRegistry();
+            const base = router.getCapabilities(decision.provider);
+            const record = registry.getCapability(decision.provider, decision.model);
+            // §6 — the external catalogue supplies `cost`/`ecosystem` PRIORS only (never measurements), and
+            // only while the feed is switched on; `externalPriorsFor` enforces that gate itself. Each one
+            // carries the source it came from, so the scorecard can print a borrowed number AS borrowed.
+            const external = externalPriorsFor(decision.provider, decision.model);
+            const externalPriors = {};
+            const priorLabels = {};
+            for (const p of external) {
+                externalPriors[p.parameter] = p.value;
+                priorLabels[p.parameter] = { source: p.source, fetchedAt: p.fetchedAt };
+            }
+            const priors = {
+                accuracy: base.reasoning,
+                performance: base.speed,
+                ...externalPriors,
+            };
+            // `accuracy`'s prior is the provider's own declared baseline (the same one
+            // the router's floor uses); anything the feed supplied beats the declared default, so the TIER
+            // below is derived from the same value the line above prints — they cannot disagree.
+            const view = (parameter) => parameter === 'accuracy'
+                ? effectiveParameter(record, 'accuracy', base.reasoning)
+                : effectiveParameter(record, parameter, priors[parameter] ?? DEFAULT_PRIORS[parameter] ?? 0);
+            console.log('');
+            logger.highlight('  ── Capability scorecard (measured) ──');
+            console.log(`   ${decision.provider}/${decision.model}`);
+            for (const line of capabilityLines(record, priors, priorLabels))
+                console.log(`     ${line}`);
+            console.log(`     tier ${deriveTier({ accuracy: view('accuracy'), robustness: view('robustness'), ecosystem: view('ecosystem') })}`);
+            console.log('     (0 samples = the declared prior; values fold in real turns, calls and latencies — never from the model id)');
+        }
+        catch {
+            // Best-effort — an audit section must never break `model explain`.
+        }
+        // Bundle 31/33 — ACCEPTANCE BY MEASUREMENT, read-only. Rendered through the
+        // SAME `formatAcceptanceSummary` that `nuvira rate --stats` and the dashboard
+        // Trace card use, so all three surfaces describe the one corpus identically. The
+        // decision's own pair is focused first; the harness-level fit
+        // `P(accepted | features)` follows. NOTHING routes on it, and when the sample is
+        // too thin it says WHY instead of printing a number that would read as one.
+        try {
+            const pairKey = `${decision.provider}/${decision.model}`;
+            console.log('');
+            logger.highlight('  ── Acceptance (labelled turns, read-only) ──');
+            for (const line of formatAcceptanceSummary(acceptanceSummary(), pairKey)) {
+                console.log(`   ${line}`);
+            }
+        }
+        catch {
+            // Best-effort — an audit section must never break `model explain`.
+        }
         // M2.4: governance transparency — show policy-eliminated providers so the
         // user sees WHY a provider is absent from the ranking (not just that it
         // is). Renders only when the admin policy actually blocked something.