@alexeiled/pi-model-router 0.6.4 → 0.7.0

package/extensions/state.ts

@@ -8,6 +8,7 @@ import {
   parseCanonicalModelRef,
 } from './config';
 import type {
+  JevContextMetrics,
   JevDiagnostics,
   PersistedStateInput,
   RouterLastProfileState,
@@ -15,7 +16,14 @@ import type {
   RouterPinByProfile,
   RoutingDecision,
 } from './types';
-import { isAdvisorOutcome, isRoutingReasonCode, JEV_OUTCOMES } from './types';
+import {
+  isAdvisorOutcome,
+  isBypassReason,
+  isRoutingReasonCode,
+  JEV_OUTCOMES,
+  JEV_RESPONSE_ISSUES,
+  JEV_SELECTION_BASES,
+} from './types';
 
 const LAST_PROFILE_STATE_FILE = 'model-router-state.json';
 
@@ -144,12 +152,35 @@ export const isRouterPersistedState = (
   );
 };
 
+const snapshotContextMetrics = (
+  value: unknown,
+): JevContextMetrics | undefined => {
+  if (!isObjectRecord(value)) return undefined;
+  const result: JevContextMetrics = {
+    currentRequestTokens: 0,
+    historyTokens: 0,
+    toolTokens: 0,
+    historyTurns: 0,
+    toolResults: 0,
+    truncatedBlocks: 0,
+  };
+  for (const key of Object.keys(result) as (keyof JevContextMetrics)[]) {
+    const number = value[key];
+    if (!isFiniteNumber(number) || !Number.isSafeInteger(number) || number < 0)
+      return undefined;
+    result[key] = number;
+  }
+  return result;
+};
+
 const snapshotJev = (value: unknown): JevDiagnostics | undefined => {
   if (!isObjectRecord(value)) return undefined;
   const outcome = JEV_OUTCOMES.find((entry) => entry === value.outcome);
   if (!outcome || !isFiniteNumber(value.latencyMs) || value.latencyMs < 0)
     return undefined;
   const result: JevDiagnostics = { outcome, latencyMs: value.latencyMs };
+  const context = snapshotContextMetrics(value.context);
+  if (context) result.context = context;
   if (
     typeof value.requestId === 'string' &&
     /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/.test(value.requestId)
@@ -167,17 +198,35 @@ const snapshotJev = (value: unknown): JevDiagnostics | undefined => {
     result.resolvedModel = value.resolvedModel;
   if (isRouterTier(value.choice) || value.choice === 'uncertain')
     result.choice = value.choice;
-  for (const key of ['confidence', 'probability', 'threshold'] as const) {
+  if (isRouterTier(value.selectedTier))
+    result.selectedTier = value.selectedTier;
+  const basis = JEV_SELECTION_BASES.find(
+    (entry) => entry === value.selectionBasis,
+  );
+  if (basis) result.selectionBasis = basis;
+  for (const key of [
+    'confidence',
+    'probability',
+    'routeProbability',
+    'threshold',
+    'probabilityThreshold',
+  ] as const) {
     const number = value[key];
     if (isFiniteNumber(number) && number >= 0 && number <= 1)
       result[key] = number;
   }
+  const issue = JEV_RESPONSE_ISSUES.find(
+    (entry) => entry === value.responseIssue,
+  );
+  if (issue) result.responseIssue = issue;
   for (const key of [
     'startedAt',
     'timeoutMs',
     'candidateCount',
-    'contextChars',
+    'estimatedInputTokens',
+    'actualInputTokens',
     'httpStatus',
+    'attempts',
   ] as const) {
     const number = value[key];
     if (isFiniteNumber(number) && Number.isSafeInteger(number) && number >= 0)
@@ -209,6 +258,9 @@ export const snapshotDecision = (
       ? decision.errorClass
       : undefined,
   advisor: isAdvisorOutcome(decision.advisor) ? decision.advisor : undefined,
+  bypassReason: isBypassReason(decision.bypassReason)
+    ? decision.bypassReason
+    : undefined,
   jev: snapshotJev(decision.jev),
   reuse:
     decision.reuse === 'same-turn' ||

package/extensions/types.ts

@@ -1,4 +1,5 @@
 import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
+import type { Context } from '@earendil-works/pi-ai';
 
 // Descending routing complexity; all tier iteration and ranking derives here.
 export const ROUTER_TIERS = ['high', 'medium', 'low', 'micro'] as const;
@@ -21,6 +22,8 @@ export interface ModelDefinition {
 export interface ClassifierConfig {
   model: string;
   thinking?: ThinkingLevel | undefined;
+  /** Total classifier budget in ms; `DEFAULT_CLASSIFIER_TIMEOUT_MS` when omitted. */
+  timeoutMs?: number | undefined;
 }
 
 export interface RoutedTierConfig {
@@ -40,6 +43,36 @@ export interface RoutedTierConfig {
   resolvedThinkingLevels?: ThinkingLevel[] | undefined;
 }
 
+export interface JevContextConfig {
+  previousTurns: number;
+  maxHistoryTokens: number;
+  toolResults: 'none' | 'last' | 'last-error';
+  maxToolTokens: number;
+}
+export interface JevRetryConfig {
+  /** HTTP attempts in total; 1 disables retries. */
+  maxAttempts: number;
+  /** First backoff delay; doubled per attempt, raised by `Retry-After`. */
+  backoffMs: number;
+}
+export interface JevTextExcerpt {
+  text: string;
+  truncated: boolean;
+}
+export interface JevContextState {
+  currentRequest: JevTextExcerpt;
+  recentDialogue: (JevTextExcerpt & { role: 'user' | 'assistant' })[];
+  recentToolEvidence: (JevTextExcerpt & { isError: boolean })[];
+}
+export interface JevContextMetrics {
+  currentRequestTokens: number;
+  historyTokens: number;
+  toolTokens: number;
+  historyTurns: number;
+  toolResults: number;
+  truncatedBlocks: number;
+}
+
 export interface JevConfig {
   enabled: boolean;
   apiKey: string;
@@ -47,7 +80,10 @@ export interface JevConfig {
   model: string;
   timeoutMs: number;
   confidenceThreshold: number;
-  maxStateChars: number;
+  probabilityThreshold: number;
+  maxStateTokens: number;
+  context?: JevContextConfig | undefined;
+  retry?: JevRetryConfig | undefined;
   mode: 'advisory';
 }
 
@@ -104,27 +140,46 @@ export interface JevDependencies {
 }
 
 export interface JevRequest {
-  taskSummary: string;
+  context: Context;
   candidates: readonly JevRouteCandidate[];
   profile: JevProfileConfig | undefined;
+  /** Local fallback tier; abstention mass is assigned to it, never inferred remotely. */
+  baselineTier: RouterTier;
   /** Absolute monotonic deadline supplied by the routing orchestrator. */
   routingDeadline: number;
   signal?: AbortSignal | undefined;
 }
 
+export const JEV_SELECTION_BASES = ['choice', 'probability'] as const;
+export type JevSelectionBasis = (typeof JEV_SELECTION_BASES)[number];
+
+/** Local validation codes; remote error text is never retained. */
+export const JEV_RESPONSE_ISSUES = [
+  'unreadable-body',
+  'missing-answer',
+  'unexpected-answer-type',
+  'unknown-choice',
+  'invalid-confidence',
+  'distribution-keys',
+  'distribution-sum',
+  'distribution-argmax',
+] as const;
+export type JevResponseIssue = (typeof JEV_RESPONSE_ISSUES)[number];
+
 export const JEV_OUTCOMES = [
   'selected',
   'uncertain',
-  'low-confidence',
   'invalid-response',
   'http-error',
   'network-error',
   'deadline',
   'cancelled',
   'unavailable',
+  'input-too-large',
 ] as const;
 export type JevOutcome = (typeof JEV_OUTCOMES)[number];
 export interface JevDiagnostics {
+  context?: JevContextMetrics | undefined;
   /** Locally generated per HTTP request, shared by reusers; never supplied by Jev. */
   requestId?: string | undefined;
   outcome: JevOutcome;
@@ -133,13 +188,23 @@ export interface JevDiagnostics {
   model?: string | undefined;
   resolvedModel?: string | undefined;
   choice?: RouterTier | 'uncertain' | undefined;
+  /** Acted-on tier, which a conservative probability selection can raise above `choice`. */
+  selectedTier?: RouterTier | undefined;
+  selectionBasis?: JevSelectionBasis | undefined;
   confidence?: number | undefined;
   probability?: number | undefined;
+  /** Cumulative probability of the selected tier and every lower tier. */
+  routeProbability?: number | undefined;
   threshold?: number | undefined;
+  probabilityThreshold?: number | undefined;
   timeoutMs?: number | undefined;
   candidateCount?: number | undefined;
-  contextChars?: number | undefined;
+  estimatedInputTokens?: number | undefined;
+  actualInputTokens?: number | undefined;
   httpStatus?: number | undefined;
+  /** HTTP attempts made, including the retry of a documented transient status. */
+  attempts?: number | undefined;
+  responseIssue?: JevResponseIssue | undefined;
 }
 export interface JevResult {
   advice?: JevAdvice | undefined;
@@ -195,6 +260,18 @@ export const ADVISOR_OUTCOMES = [
 export type AdvisorOutcome = (typeof ADVISOR_OUTCOMES)[number];
 export const isAdvisorOutcome = (value: unknown): value is AdvisorOutcome =>
   ADVISOR_OUTCOMES.some((outcome) => outcome === value);
+/** Why a configured advisor was not asked on this decision. */
+export const BYPASS_REASONS = [
+  'pinned',
+  'budget',
+  'single-candidate',
+  'tool-continuation',
+  'no-user-turn',
+  'turn-advised',
+] as const;
+export type BypassReason = (typeof BYPASS_REASONS)[number];
+export const isBypassReason = (value: unknown): value is BypassReason =>
+  BYPASS_REASONS.some((reason) => reason === value);
 
 export interface RoutingDecision {
   profile: string;
@@ -207,6 +284,7 @@ export interface RoutingDecision {
   routingLatencyMs?: number | undefined;
   errorClass?: RoutingErrorClass | undefined;
   advisor?: AdvisorOutcome | undefined;
+  bypassReason?: BypassReason | undefined;
   jev?: JevDiagnostics | undefined;
   reuse?: 'same-turn' | 'shared' | 'continuation' | undefined;
   thinking: ThinkingLevel;

package/extensions/ui.ts

@@ -25,6 +25,25 @@ export const formatDecisionSource = (decision: RoutingDecision): string =>
     ? decision.reasonCode
     : '';
 
+const formatBypassReason = (decision: RoutingDecision): string => {
+  switch (decision.bypassReason) {
+    case 'pinned':
+      return `pinned ${decision.tier}`;
+    case 'budget':
+      return 'over budget';
+    case 'single-candidate':
+      return `only ${decision.tier} eligible`;
+    case 'tool-continuation':
+      return 'tool turn';
+    case 'no-user-turn':
+      return 'no user turn';
+    case 'turn-advised':
+      return 'turn already advised';
+    default:
+      return '';
+  }
+};
+
 export const formatAdvisorLabel = (
   decision: RoutingDecision,
 ): string | undefined => {
@@ -32,8 +51,10 @@ export const formatAdvisorLabel = (
   switch (decision.advisor) {
     case 'none':
       return 'local baseline';
-    case 'bypassed':
-      return 'advice bypassed';
+    case 'bypassed': {
+      const reason = formatBypassReason(decision);
+      return reason ? `advice skipped: ${reason}` : 'advice bypassed';
+    }
     case 'jev':
       return '🧭 Jev ✓';
     case 'jev-fallback':
@@ -76,6 +97,11 @@ export const formatAdvisorDetail = (
     );
     if (metrics.choice && metrics.choice !== 'uncertain')
       parts.push(`choice=${metrics.choice}`);
+    if (metrics.selectedTier && metrics.selectedTier !== metrics.choice)
+      parts.push(`selected=${metrics.selectedTier}`);
+    if (metrics.selectionBasis) parts.push(`basis=${metrics.selectionBasis}`);
+    if (metrics.routeProbability !== undefined)
+      parts.push(`route-p=${(metrics.routeProbability * 100).toFixed(1)}%`);
     if (metrics.probability !== undefined)
       parts.push(
         `${metrics.outcome === 'uncertain' ? 'abstention-p' : 'p'}=${(metrics.probability * 100).toFixed(1)}%`,
@@ -86,14 +112,38 @@ export const formatAdvisorDetail = (
       );
     if (metrics.threshold !== undefined && metrics.outcome !== 'uncertain')
       parts.push(`threshold=${(metrics.threshold * 100).toFixed(1)}%`);
+    if (
+      metrics.probabilityThreshold !== undefined &&
+      metrics.selectionBasis === 'probability'
+    )
+      parts.push(
+        `route-threshold=${(metrics.probabilityThreshold * 100).toFixed(1)}%`,
+      );
     if (metrics.timeoutMs !== undefined)
       parts.push(`budget=${metrics.timeoutMs}ms`);
     if (metrics.candidateCount !== undefined)
       parts.push(`candidates=${metrics.candidateCount}`);
-    if (metrics.contextChars !== undefined)
-      parts.push(`context=${metrics.contextChars} chars`);
+    if (metrics.context) {
+      const context = metrics.context;
+      parts.push(
+        `state≈${context.currentRequestTokens + context.historyTokens + context.toolTokens} tokens: ${context.currentRequestTokens} current + ${context.historyTokens} dialogue/${context.historyTurns} turns + ${context.toolTokens} tool/${context.toolResults} results; truncated=${context.truncatedBlocks}`,
+      );
+    }
+    if (metrics.estimatedInputTokens !== undefined)
+      parts.push(`request≈${metrics.estimatedInputTokens} tokens`);
+    if (metrics.actualInputTokens !== undefined)
+      parts.push(`Jev usage=${metrics.actualInputTokens} input tokens`);
     if (metrics.httpStatus !== undefined)
       parts.push(`HTTP ${metrics.httpStatus}`);
+    if (metrics.attempts !== undefined && metrics.attempts > 1)
+      parts.push(`attempts=${metrics.attempts}`);
+    if (metrics.responseIssue) parts.push(`response=${metrics.responseIssue}`);
+    if (metrics.httpStatus === 401)
+      parts.push('Check the user-config Jev API key.');
+    if (metrics.httpStatus === 422)
+      parts.push('Jev rejected the request shape.');
+    if (metrics.httpStatus === 429 || metrics.httpStatus === 529)
+      parts.push('Transient Jev limit; the router retried once within budget.');
   } else if (decision.errorClass) {
     parts.push(decision.errorClass);
   }
@@ -119,10 +169,10 @@ export const formatAdvisorFooter = (
   let summary: string;
   switch (metrics.outcome) {
     case 'selected':
-      summary = `→ ${metrics.choice ?? decision.tier}${confidence}`;
-      break;
-    case 'low-confidence':
-      summary = `${metrics.choice ?? 'choice'}${confidence}${metrics.threshold !== undefined ? ` <${Math.round(metrics.threshold * 100)}%` : ''} → baseline`;
+      summary =
+        metrics.selectionBasis === 'probability'
+          ? `${metrics.choice ?? 'choice'}${confidence}${metrics.threshold !== undefined ? ` <${Math.round(metrics.threshold * 100)}%` : ''} → ${metrics.selectedTier ?? decision.tier}`
+          : `→ ${metrics.choice ?? decision.tier}${confidence}`;
       break;
     case 'uncertain':
       summary = ': no tier chosen → baseline';
@@ -137,7 +187,7 @@ export const formatAdvisorFooter = (
       summary = ': network error → baseline';
       break;
     case 'invalid-response':
-      summary = ': invalid response → baseline';
+      summary = `: invalid response${metrics.responseIssue ? ` (${metrics.responseIssue})` : ''} → baseline`;
       break;
     case 'cancelled':
       summary = ': cancelled';
@@ -145,6 +195,9 @@ export const formatAdvisorFooter = (
     case 'unavailable':
       summary = `: ${metrics.choice ? 'target' : 'advice'} unavailable → baseline`;
       break;
+    case 'input-too-large':
+      summary = ': estimated request too large → baseline';
+      break;
   }
   const latency =
     metrics.latencyMs >= 1000

package/model-router.example.json

@@ -8,7 +8,15 @@
     "model": "jev-1.13.0",
     "timeoutMs": 1500,
     "confidenceThreshold": 0.65,
-    "maxStateChars": 12000,
+    "probabilityThreshold": 0.8,
+    "maxStateTokens": 3000,
+    "context": {
+      "previousTurns": 2,
+      "maxHistoryTokens": 500,
+      "toolResults": "last-error",
+      "maxToolTokens": 250
+    },
+    "retry": { "maxAttempts": 2, "backoffMs": 400 },
     "mode": "advisory"
   },
   "classifierModel": "flash",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/pi-model-router",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "type": "module",
   "files": [
     "extensions",