@alexeiled/pi-model-router 0.5.1 → 0.6.0

package/extensions/state.ts

@@ -8,12 +8,13 @@ import {
   parseCanonicalModelRef,
 } from './config';
 import type {
+  PersistedStateInput,
   RouterLastProfileState,
   RouterPersistedState,
   RouterPinByProfile,
-  RouterThinkingByProfile,
   RoutingDecision,
 } from './types';
+import { isRoutingReasonCode } from './types';
 
 const LAST_PROFILE_STATE_FILE = 'model-router-state.json';
 
@@ -30,20 +31,33 @@ const isModelRef = (value: unknown) => {
     return false;
   }
 };
+
+// Historical snapshots remain readable, but obsolete prompt-derived sources
+// are sanitized to `legacy` and never become live routing behavior again.
+const OBSOLETE_REASON_CODES = new Set([
+  'custom-rule',
+  'micro-mechanical',
+  'heuristic',
+  'safety-floor',
+  'budget-floor-conflict',
+]);
+const isPersistedReasonCode = (value: unknown): boolean =>
+  isRoutingReasonCode(value) ||
+  (typeof value === 'string' && OBSOLETE_REASON_CODES.has(value));
+
 const isDecision = (value: unknown): value is RoutingDecision =>
   isObjectRecord(value) &&
   isRouterTier(value.tier) &&
   isPhase(value.phase) &&
   isThinkingLevel(value.thinking) &&
   isFiniteNumber(value.timestamp) &&
-  [
-    'profile',
-    'targetProvider',
-    'targetModelId',
-    'targetLabel',
-    'reasoning',
-  ].every((key) => typeof value[key] === 'string') &&
-  ['isClassifier', 'isFallback', 'isBudgetForced', 'isRuleMatched'].every(
+  ['profile', 'targetProvider', 'targetModelId', 'targetLabel'].every(
+    (key) => typeof value[key] === 'string',
+  ) &&
+  (value.reasonCode === undefined
+    ? typeof value.reasoning === 'string'
+    : isPersistedReasonCode(value.reasonCode)) &&
+  ['isClassifier', 'isFallback', 'isBudgetForced'].every(
     (key) => value[key] === undefined || typeof value[key] === 'boolean',
   );
 const isMap = (value: unknown, validate: (entry: unknown) => boolean) =>
@@ -128,29 +142,64 @@ export const isRouterPersistedState = (
   );
 };
 
-export const buildPersistedState = (
-  routerEnabled: boolean,
-  selectedProfile: string | undefined,
-  pinnedTierByProfile: RouterPinByProfile,
-  thinkingByProfile: RouterThinkingByProfile,
-  debugEnabled: boolean,
-  widgetEnabled: boolean,
-  debugHistory: RoutingDecision[],
-  lastDecision: RoutingDecision | undefined,
-  lastNonRouterModel: string | undefined,
-  accumulatedCost: number,
-): RouterPersistedState => {
+// Copy only the decision contract, never incidental runtime properties.
+export const snapshotDecision = (
+  decision: RoutingDecision,
+): RoutingDecision => ({
+  profile: decision.profile,
+  tier: decision.tier,
+  phase: decision.phase,
+  targetProvider: decision.targetProvider,
+  targetModelId: decision.targetModelId,
+  targetLabel: decision.targetLabel,
+  reasonCode: isRoutingReasonCode(decision.reasonCode)
+    ? decision.reasonCode
+    : 'legacy',
+  routingLatencyMs:
+    isFiniteNumber(decision.routingLatencyMs) && decision.routingLatencyMs >= 0
+      ? decision.routingLatencyMs
+      : undefined,
+  errorClass:
+    decision.errorClass === 'advisor-unavailable' ||
+    decision.errorClass === 'deadline'
+      ? decision.errorClass
+      : undefined,
+  thinking: decision.thinking,
+  timestamp: decision.timestamp,
+  isClassifier: decision.isClassifier,
+  isFallback: decision.isFallback,
+  isBudgetForced: decision.isBudgetForced,
+});
+
+export const buildPersistedState = ({
+  routerEnabled,
+  selectedProfile,
+  pinnedTierByProfile,
+  thinkingByProfile,
+  debugEnabled,
+  widgetEnabled,
+  debugHistory,
+  lastDecision,
+  lastNonRouterModel,
+  accumulatedCost,
+}: PersistedStateInput): RouterPersistedState => {
+  const pinByProfile: RouterPinByProfile = {};
+  for (const [profile, tier] of Object.entries(pinnedTierByProfile)) {
+    if (tier) pinByProfile[profile] = tier;
+  }
   return structuredClone({
     enabled: routerEnabled,
     selectedProfile: selectedProfile ?? '',
-    pinTier: selectedProfile ? pinnedTierByProfile[selectedProfile] : undefined,
-    pinByProfile: { ...pinnedTierByProfile },
+    ...(selectedProfile && pinnedTierByProfile[selectedProfile]
+      ? { pinTier: pinnedTierByProfile[selectedProfile] }
+      : {}),
+    pinByProfile,
     thinkingByProfile: { ...thinkingByProfile },
     debugEnabled,
     widgetEnabled,
-    debugHistory,
+    debugHistory: debugHistory.map(snapshotDecision),
     lastPhase: lastDecision?.phase,
-    lastDecision,
+    lastDecision: lastDecision ? snapshotDecision(lastDecision) : undefined,
     lastNonRouterModel,
     accumulatedCost,
     timestamp: Date.now(),

package/extensions/types.ts

@@ -1,60 +1,137 @@
 import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 
-export type RouterTier = 'high' | 'medium' | 'low';
+// Descending routing complexity; all tier iteration and ranking derives here.
+export const ROUTER_TIERS = ['high', 'medium', 'low', 'micro'] as const;
+export type RouterTier = (typeof ROUTER_TIERS)[number];
+export type ClassifierTier = RouterTier;
 export type RouterPin = RouterTier | 'auto';
 export type RouterPhase = 'planning' | 'implementation' | 'lightweight';
 export type RouterPinByProfile = Partial<Record<string, RouterTier>>;
 export type RouterThinkingByTier = Partial<Record<RouterTier, ThinkingLevel>>;
 export type RouterThinkingByProfile = Record<string, RouterThinkingByTier>;
 
-export interface RoutingRule {
-  matches: string | string[];
-  tier: RouterTier;
-  reason?: string;
-}
-
 export interface ModelDefinition {
   model: string;
-  contextWindow?: number;
-  maxTokens?: number;
-  reasoning?: boolean;
-  thinkingLevels?: ThinkingLevel[];
+  contextWindow?: number | undefined;
+  maxTokens?: number | undefined;
+  reasoning?: boolean | undefined;
+  thinkingLevels?: ThinkingLevel[] | undefined;
 }
 
 export interface ClassifierConfig {
   model: string;
-  thinking?: ThinkingLevel;
+  thinking?: ThinkingLevel | undefined;
 }
 
 export interface RoutedTierConfig {
   model: string;
-  thinking?: ThinkingLevel;
-  fallbacks?: string[];
-  contextWindow?: number;
-  maxTokens?: number;
-  reasoning?: boolean;
-  thinkingLevels?: ThinkingLevel[];
-  resolvedContextWindow?: number;
-  resolvedMaxTokens?: number;
-  resolvedThinkingLevels?: ThinkingLevel[];
+  /** False for normalization defaults; omitted on legacy in-memory profiles. */
+  thinkingExplicit?: boolean | undefined;
+  thinking?: ThinkingLevel | undefined;
+  fallbacks?: string[] | undefined;
+  /** Canonical targets and exact alias metadata, in the same order as fallbacks. */
+  resolvedFallbacks?: ModelDefinition[] | undefined;
+  contextWindow?: number | undefined;
+  maxTokens?: number | undefined;
+  reasoning?: boolean | undefined;
+  thinkingLevels?: ThinkingLevel[] | undefined;
+  resolvedContextWindow?: number | undefined;
+  resolvedMaxTokens?: number | undefined;
+  resolvedThinkingLevels?: ThinkingLevel[] | undefined;
+}
+
+export interface JevConfig {
+  enabled: boolean;
+  apiKey: string;
+  endpoint: string;
+  model: string;
+  timeoutMs: number;
+  confidenceThreshold: number;
+  maxStateChars: number;
+  mode: 'advisory';
+}
+
+export interface JevProfileConfig {
+  enabled: boolean;
 }
 
 export interface RouterProfile {
-  high?: RoutedTierConfig;
-  medium?: RoutedTierConfig;
-  low?: RoutedTierConfig;
+  baselineTier?: RouterTier | undefined;
+  jev?: JevProfileConfig | undefined;
+  high?: RoutedTierConfig | undefined;
+  medium?: RoutedTierConfig | undefined;
+  low?: RoutedTierConfig | undefined;
+  micro?: RoutedTierConfig | undefined;
 }
 
 export interface RouterConfig {
-  debug?: boolean;
-  classifierModel?: ClassifierConfig;
-  phaseBias?: number;
-  maxSessionBudget?: number;
-  rules?: RoutingRule[];
+  jev?: JevConfig | undefined;
+  debug?: boolean | undefined;
+  classifierModel?: ClassifierConfig | undefined;
+  maxSessionBudget?: number | undefined;
   profiles: Record<string, RouterProfile>;
-  models?: Record<string, ModelDefinition>;
+  models?: Record<string, ModelDefinition> | undefined;
+}
+
+export interface RouterStatusState {
+  routerEnabled: boolean;
+  selectedProfile: string | undefined;
+  pinnedTierByProfile: RouterPinByProfile;
+  lastDecision: RoutingDecision | undefined;
+  lastNonRouterModel: string | undefined;
+  accumulatedCost: number;
+  widgetEnabled: boolean;
+  maxSessionBudget: number | undefined;
+}
+
+export interface RoutePair {
+  tier: RouterTier;
+  model: string;
+  thinking: ThinkingLevel;
+}
+
+export interface JevRouteCandidate extends RoutePair {
+  id: string;
+}
+
+export interface JevDependencies {
+  fetch?: typeof fetch;
+  now?: () => number;
+}
+
+export interface JevRequest {
+  taskSummary: string;
+  candidates: readonly JevRouteCandidate[];
+  profile: JevProfileConfig | undefined;
+  /** Absolute monotonic deadline supplied by the routing orchestrator. */
+  routingDeadline: number;
+  signal?: AbortSignal | undefined;
+}
+
+/** Only allowlisted local identity and numeric diagnostics cross the adapter boundary. */
+export interface JevAdvice {
+  candidateId: string;
+  confidence: number;
+  latencyMs: number;
 }
 
+export const ROUTING_REASON_CODES = [
+  'baseline',
+  'pinned',
+  'continuation',
+  'classifier',
+  'jev',
+  'fallback',
+  'budget',
+  'legacy',
+] as const;
+export type RoutingReasonCode = (typeof ROUTING_REASON_CODES)[number];
+export const isRoutingReasonCode = (
+  value: unknown,
+): value is RoutingReasonCode =>
+  ROUTING_REASON_CODES.some((code) => code === value);
+export type RoutingErrorClass = 'advisor-unavailable' | 'deadline';
+
 export interface RoutingDecision {
   profile: string;
   tier: RouterTier;
@@ -62,13 +139,14 @@ export interface RoutingDecision {
   targetProvider: string;
   targetModelId: string;
   targetLabel: string;
-  reasoning: string;
+  reasonCode: RoutingReasonCode;
+  routingLatencyMs?: number | undefined;
+  errorClass?: RoutingErrorClass | undefined;
   thinking: ThinkingLevel;
   timestamp: number;
-  isClassifier?: boolean;
-  isFallback?: boolean;
-  isBudgetForced?: boolean;
-  isRuleMatched?: boolean;
+  isClassifier?: boolean | undefined;
+  isFallback?: boolean | undefined;
+  isBudgetForced?: boolean | undefined;
 }
 
 export interface RouterLastProfileState {
@@ -76,34 +154,52 @@ export interface RouterLastProfileState {
   timestamp: number;
 }
 
+export interface PersistedStateInput {
+  routerEnabled: boolean;
+  selectedProfile: string | undefined;
+  pinnedTierByProfile: RouterPinByProfile;
+  thinkingByProfile: RouterThinkingByProfile;
+  debugEnabled: boolean;
+  widgetEnabled: boolean;
+  debugHistory: RoutingDecision[];
+  lastDecision: RoutingDecision | undefined;
+  lastNonRouterModel: string | undefined;
+  accumulatedCost: number;
+}
+
 export interface RouterPersistedState {
   enabled: boolean;
   selectedProfile: string;
-  pinTier?: RouterTier;
-  pinByProfile?: RouterPinByProfile;
-  thinkingByProfile?: RouterThinkingByProfile;
-  debugEnabled?: boolean;
-  widgetEnabled?: boolean;
-  debugHistory?: RoutingDecision[];
-  lastPhase?: RouterPhase;
-  lastDecision?: RoutingDecision;
-  lastNonRouterModel?: string;
-  accumulatedCost?: number;
+  pinTier?: RouterTier | undefined;
+  pinByProfile?: RouterPinByProfile | undefined;
+  thinkingByProfile?: RouterThinkingByProfile | undefined;
+  debugEnabled?: boolean | undefined;
+  widgetEnabled?: boolean | undefined;
+  debugHistory?: RoutingDecision[] | undefined;
+  lastPhase?: RouterPhase | undefined;
+  lastDecision?: RoutingDecision | undefined;
+  lastNonRouterModel?: string | undefined;
+  accumulatedCost?: number | undefined;
   timestamp: number;
 }
 
+export interface RawRouterConfig {
+  jev?: unknown;
+  debug?: unknown;
+  classifierModel?: unknown;
+  phaseBias?: unknown;
+  maxSessionBudget?: unknown;
+  rules?: unknown;
+  profiles?: unknown;
+  models?: unknown;
+}
+
 export interface ConfigLoadResult {
   config: RouterConfig;
   warnings: string[];
 }
 
 export interface ParsedConfigFile {
-  config: Partial<RouterConfig>;
+  config: RawRouterConfig;
   warnings: string[];
 }
-
-export interface CustomSessionEntry {
-  type: string;
-  customType?: string;
-  data?: unknown;
-}

package/extensions/ui.ts

@@ -1,27 +1,27 @@
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
 import type {
-  RouterConfig,
   RouterPinByProfile,
+  RouterStatusState,
   RouterThinkingByProfile,
   RoutingDecision,
 } from './types';
-
-const getEffectiveThinking = (
-  thinkingByProfile: RouterThinkingByProfile,
-  profileName: string,
-  decision: RoutingDecision,
-) => thinkingByProfile[profileName]?.[decision.tier] ?? decision.thinking;
+import { isRoutingReasonCode } from './types';
 
 const getDecisionFlags = (decision: RoutingDecision): string[] => {
   const flags: string[] = [];
   if (decision.isFallback) flags.push('fallback');
   if (decision.isBudgetForced) flags.push('budget-limit');
-  if (decision.isRuleMatched) flags.push('rule');
   return flags;
 };
 
+export const formatDecisionSource = (decision: RoutingDecision): string =>
+  isRoutingReasonCode(decision.reasonCode) && decision.reasonCode !== 'legacy'
+    ? decision.reasonCode
+    : '';
+
 export const formatDecision = (decision: RoutingDecision): string => {
-  return `${decision.profile}: ${decision.tier} -> ${decision.targetProvider}/${decision.targetModelId} [${decision.thinking}] (${decision.reasoning})`;
+  const source = formatDecisionSource(decision);
+  return `${decision.profile}: ${decision.tier} -> ${decision.targetProvider}/${decision.targetModelId} [${decision.thinking}]${source ? ` (${source})` : ''}`;
 };
 
 export const formatPinSummary = (
@@ -53,16 +53,18 @@ export const formatModelRef = (ref: string | undefined): string => {
 
 export const updateStatus = (
   ctx: ExtensionContext,
-  routerEnabled: boolean,
-  selectedProfile: string | undefined,
-  pinnedTierByProfile: RouterPinByProfile,
-  thinkingByProfile: RouterThinkingByProfile,
-  lastDecision: RoutingDecision | undefined,
-  lastNonRouterModel: string | undefined,
-  accumulatedCost: number,
-  widgetEnabled: boolean,
-  currentConfig: RouterConfig,
+  state: RouterStatusState,
 ) => {
+  const {
+    routerEnabled,
+    selectedProfile,
+    pinnedTierByProfile,
+    lastDecision,
+    lastNonRouterModel,
+    accumulatedCost,
+    widgetEnabled,
+    maxSessionBudget,
+  } = state;
   const activeRouterProfile = routerEnabled ? selectedProfile : undefined;
   const statusProfile = selectedProfile ?? 'none';
   const activePin = selectedProfile
@@ -73,16 +75,11 @@ export const updateStatus = (
   if (activeRouterProfile) {
     const matchesProfile =
       lastDecision && lastDecision.profile === activeRouterProfile;
-    const matchesPin = activePin ? lastDecision?.tier === activePin : true;
+    const matchesPin = !activePin || lastDecision?.tier === activePin;
 
     let statusText: string;
     if (lastDecision && matchesProfile && matchesPin) {
-      const effectiveThinking = getEffectiveThinking(
-        thinkingByProfile,
-        activeRouterProfile,
-        lastDecision,
-      );
-      statusText = `router:${activeRouterProfile}${pinLabel} -> ${lastDecision.tier} -> ${lastDecision.targetProvider}/${lastDecision.targetModelId} (${effectiveThinking})`;
+      statusText = `router:${activeRouterProfile}${pinLabel} -> ${lastDecision.tier} -> ${lastDecision.targetProvider}/${lastDecision.targetModelId} (${lastDecision.thinking})`;
     } else {
       statusText = `router:${activeRouterProfile}${pinLabel} -> waiting`;
     }
@@ -101,22 +98,23 @@ export const updateStatus = (
     `Profile: ${statusProfile}${activeRouterProfile ? ' (active)' : ''}`,
     `Pin: ${activePin ?? 'auto'}`,
     `Cost: $${accumulatedCost.toFixed(4)}` +
-      (currentConfig.maxSessionBudget
-        ? ` / $${currentConfig.maxSessionBudget.toFixed(2)}`
-        : ''),
+      (maxSessionBudget ? ` / $${maxSessionBudget.toFixed(2)}` : ''),
   ];
   if (lastDecision && lastDecision.profile === statusProfile) {
-    const effectiveThinking = getEffectiveThinking(
-      thinkingByProfile,
-      statusProfile,
-      lastDecision,
-    );
     const flags = getDecisionFlags(lastDecision);
     const flagsStr = flags.length > 0 ? ` [${flags.join(',')}]` : '';
 
     widgetLines.push(
-      `Route: ${lastDecision.tier}${flagsStr} -> ${lastDecision.targetProvider}/${lastDecision.targetModelId} (${effectiveThinking})`,
+      `Route: ${lastDecision.tier}${flagsStr} -> ${lastDecision.targetProvider}/${lastDecision.targetModelId} (${lastDecision.thinking})`,
       `Phase: ${lastDecision.phase}`,
+      `Source: ${formatDecisionSource(lastDecision) || 'unknown'}`,
+      ...(Number.isFinite(lastDecision.routingLatencyMs)
+        ? [`Routing: ${Math.round(lastDecision.routingLatencyMs ?? 0)}ms`]
+        : []),
+      ...(lastDecision.errorClass === 'deadline' ||
+      lastDecision.errorClass === 'advisor-unavailable'
+        ? [`Routing error: ${lastDecision.errorClass}`]
+        : []),
     );
   } else if (!routerEnabled && lastNonRouterModel) {
     widgetLines.push(`Fallback: ${lastNonRouterModel}`);

package/model-router.example.json

@@ -1,7 +1,16 @@
 {
   "debug": false,
+  "jev": {
+    "enabled": false,
+    "apiKey": "<rendered by chezmoi/1Password in user config only>",
+    "endpoint": "https://api.typesafe.ai/v1/systemone",
+    "model": "jev-1.13.0",
+    "timeoutMs": 750,
+    "confidenceThreshold": 0.65,
+    "maxStateChars": 12000,
+    "mode": "advisory"
+  },
   "classifierModel": "flash",
-  "phaseBias": 0.5,
   "maxSessionBudget": 1.0,
   "models": {
     "gpt-pro": {
@@ -25,30 +34,27 @@
       "contextWindow": 200000
     }
   },
-  "rules": [
-    {
-      "matches": ["deploy", "production", "release"],
-      "tier": "high",
-      "reason": "Safety check for production tasks"
-    },
-    { "matches": "changelog", "tier": "low" }
-  ],
   "profiles": {
     "auto": {
+      "baselineTier": "medium",
+      "jev": { "enabled": false },
       "high": {
         "model": "gpt-pro",
         "thinking": "high",
         "fallbacks": ["sonnet"]
       },
       "medium": { "model": "flash", "thinking": "medium" },
-      "low": { "model": "nano", "thinking": "low" }
+      "low": { "model": "nano", "thinking": "off" },
+      "micro": { "model": "nano", "thinking": "off" }
     },
     "cheap": {
+      "jev": { "enabled": false },
       "high": { "model": "flash", "thinking": "low" },
       "medium": { "model": "nano", "thinking": "off" },
       "low": { "model": "google/gemini-flash-lite-latest", "thinking": "off" }
     },
     "deep": {
+      "jev": { "enabled": false },
       "high": {
         "model": "openai/o1-preview",
         "thinking": "xhigh",
@@ -58,6 +64,7 @@
       "low": { "model": "flash", "thinking": "low" }
     },
     "anthropic": {
+      "jev": { "enabled": false },
       "high": {
         "model": "sonnet",
         "thinking": "high"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/pi-model-router",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "files": [
     "extensions",
@@ -11,7 +11,7 @@
     "README.md",
     "CHANGELOG.md"
   ],
-  "description": "Smart per-turn model router for Pi that optimizes your AI budget and usage limits by dynamically switching LLM tiers based on task complexity, budget, and phase awareness.",
+  "description": "Independently maintained Pi model router with tiered routing, soft budget controls, classifier fallback, and custom-provider support.",
   "keywords": [
     "pi-package",
     "pi",
@@ -24,7 +24,7 @@
   "engines": {
     "node": ">=22.19.0"
   },
-  "packageManager": "npm@11.18.0",
+  "packageManager": "npm@12.0.2",
   "author": "Alexei Ledenev",
   "contributors": [
     "Ye Liu"
@@ -52,7 +52,7 @@
     "tsc": "tsc --noEmit",
     "build": "tsc",
     "prepublishOnly": "npm run check && npm test",
-    "test": "vitest run",
+    "test": "vitest run --pool=threads",
     "check": "biome check --error-on-warnings . && npm run tsc",
     "lint": "biome lint --error-on-warnings .",
     "lint:fix": "biome lint --write --error-on-warnings .",