@alexeiled/pi-model-router 0.5.2 → 0.6.1

package/extensions/routing.ts

@@ -1,20 +1,28 @@
-import type { Context } from '@earendil-works/pi-ai';
-import { parseCanonicalModelRef } from './config';
 import {
-  containsAny,
-  countToolResults,
-  countWords,
-  getLastUserText,
-  getRecentConversationText,
-} from './context';
+  type Api,
+  getSupportedThinkingLevels,
+  type Model,
+} from '@earendil-works/pi-ai';
+import { parseCanonicalModelRef } from './config';
 import type {
+  ModelDefinition,
+  RoutePair,
   RouterPhase,
   RouterProfile,
   RouterThinkingByTier,
   RouterTier,
   RoutingDecision,
-  RoutingRule,
+  RoutingReasonCode,
 } from './types';
+import { ROUTER_TIERS } from './types';
+
+/** The configured default preference order when no baseline tier is supplied. */
+export const BASELINE_TIER_ORDER: readonly RouterTier[] = [
+  'medium',
+  'high',
+  'low',
+  'micro',
+] as const;
 
 export const phaseForTier = (tier: RouterTier): RouterPhase => {
   if (tier === 'high') return 'planning';
@@ -22,317 +30,249 @@ export const phaseForTier = (tier: RouterTier): RouterPhase => {
   return 'lightweight';
 };
 
-export const resolveAvailableTier = (
-  profile: RouterProfile,
-  preferred: RouterTier,
-): RouterTier => {
-  if (profile[preferred]) return preferred;
-  // Fall "up": low → medium → high
-  const order: RouterTier[] = ['low', 'medium', 'high'];
-  const startIdx = order.indexOf(preferred);
-  for (let i = startIdx + 1; i < order.length; i++) {
-    const tier = order[i];
-    if (tier && profile[tier]) return tier;
-  }
-  // Fall "down" as last resort
-  for (let i = startIdx - 1; i >= 0; i--) {
-    const tier = order[i];
-    if (tier && profile[tier]) return tier;
-  }
-  return preferred; // unreachable if profile has ≥1 tier
-};
-
-export const buildRoutingDecision = (
-  profileName: string,
+export const resolveRoutePair = (
   profile: RouterProfile,
   tier: RouterTier,
-  phase: RouterPhase,
-  reasoning: string,
   thinkingOverrides?: RouterThinkingByTier,
-  isClassifier?: boolean,
-): RoutingDecision => {
+): RoutePair => {
   const routed = profile[tier];
-  if (!routed) {
-    throw new Error(
-      `Profile "${profileName}" has no configuration for the ${tier} tier.`,
-    );
-  }
+  if (!routed)
+    throw new Error('No eligible route: selected tier is not configured.');
   const { provider, modelId } = parseCanonicalModelRef(routed.model);
-  const baseThinking =
-    routed.thinking ??
-    (tier === 'high' ? 'high' : tier === 'low' ? 'low' : 'medium');
-  const effectiveThinking = thinkingOverrides?.[tier] ?? baseThinking;
-
   return {
-    profile: profileName,
     tier,
-    phase,
-    targetProvider: provider,
-    targetModelId: modelId,
-    targetLabel: routed.model,
-    reasoning,
-    thinking: effectiveThinking,
-    timestamp: Date.now(),
-    isClassifier,
+    model: `${provider}/${modelId}`,
+    thinking:
+      thinkingOverrides?.[tier] ??
+      routed.thinking ??
+      (tier === 'micro' ? 'off' : tier),
   };
 };
 
-export const decideRouting = (
-  context: Context,
-  profileName: string,
+/**
+ * Revalidate the actual target against the live registry. A configured effort
+ * declaration is restrictive: it can reject a route, but never grants a
+ * capability the live model does not expose.
+ */
+export const validateRoutePair = (
+  pair: RoutePair,
+  findModel: (provider: string, modelId: string) => Model<Api> | undefined,
+  imageAttached: boolean,
+  declaredLevels?: ModelDefinition['thinkingLevels'],
+): boolean => {
+  try {
+    const { provider, modelId } = parseCanonicalModelRef(pair.model);
+    if (provider === 'router') return false;
+    const model = findModel(provider, modelId);
+    return Boolean(
+      model?.input.includes(imageAttached ? 'image' : 'text') &&
+        getSupportedThinkingLevels(model).includes(pair.thinking) &&
+        (!declaredLevels ||
+          pair.thinking === 'off' ||
+          declaredLevels.includes(pair.thinking)),
+    );
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Return all generation attempts that the active profile can serve. The first
+ * route for a tier is its primary; subsequent routes are explicit generation
+ * fallbacks and remain in their configured order.
+ *
+ * Tier and fallback references are normalized before this boundary. Parse them
+ * directly so a canonical-looking model reference cannot resolve as an alias a
+ * second time.
+ */
+export const availableRoutePairs = (
   profile: RouterProfile,
-  previousDecision: RoutingDecision | undefined,
-  pinnedTier?: RouterTier,
+  findModel: (provider: string, modelId: string) => Model<Api> | undefined,
+  imageAttached: boolean,
   thinkingOverrides?: RouterThinkingByTier,
-  phaseBias = 0.5,
-  rules?: RoutingRule[],
-  isBudgetExceeded = false,
-): RoutingDecision => {
-  if (previousDecision?.profile !== profileName) previousDecision = undefined;
-  const prompt = getLastUserText(context).toLowerCase();
-  const recentConversation = getRecentConversationText(context);
-  const toolResultCount = countToolResults(context);
-  const wordCount = countWords(prompt);
-  const multiLinePrompt = prompt.split('\n').length >= 4;
+): RoutePair[] =>
+  ROUTER_TIERS.flatMap((tier) => {
+    const config = profile[tier];
+    if (!config) return [];
 
-  const explicitHighHints = [
-    'best',
-    'deep',
-    'deeply',
-    'carefully',
-    'thoroughly',
-    'robust',
-    'comprehensive',
-    'step by step',
-    'think hard',
-    'highest quality',
-    'ultrathink',
-  ];
-  const explicitLowHints = [
-    'fast',
-    'cheap',
-    'quick',
-    'quickly',
-    'brief',
-    'briefly',
-    'one sentence',
-    'one line',
-    'tiny',
-    'small',
-  ];
-  const planningKeywords = [
-    'plan',
-    'planning',
-    'architecture',
-    'architect',
-    'design',
-    'tradeoff',
-    'trade-off',
-    'research',
-    'investigate',
-    'root cause',
-    'analyze',
-    'analysis',
-    'migration',
-    'strategy',
-    'compare',
-    'options',
-    'approach',
-  ];
-  const summaryKeywords = [
-    'summarize',
-    'summary',
-    'changelog',
-    'rewrite',
-    'reformat',
-    'format',
-    'rename',
-    'explain briefly',
-    'recap',
-    'tl;dr',
-  ];
-  const implementationKeywords = [
-    'implement',
-    'code',
-    'fix',
-    'update',
-    'edit',
-    'write',
-    'refactor',
-    'add tests',
-    'patch',
-    'change',
-    'apply',
-    'continue',
-    'resume',
-    'make the changes',
-    'go ahead',
-  ];
-  const lookupKeywords = [
-    'where is',
-    'which file',
-    'show me',
-    'list',
-    'what files',
-    'find',
-    'grep',
-  ];
+    let primary: RoutePair;
+    try {
+      primary = resolveRoutePair(profile, tier, thinkingOverrides);
+    } catch {
+      return [];
+    }
 
-  let phase: RouterPhase = previousDecision?.phase ?? 'implementation';
-  let tier: RouterTier = 'medium';
-  let reasoning = 'Defaulted to medium tier for general coding work.';
-  let isRuleMatched = false;
+    return [primary.model, ...(config.fallbacks ?? [])]
+      .flatMap((ref, index) => {
+        try {
+          const { provider, modelId } = parseCanonicalModelRef(ref);
+          const model = findModel(provider, modelId);
+          const ownConfig =
+            index === 0 ? config : config.resolvedFallbacks?.[index - 1];
+          // A non-reasoning model defaults to off, but explicit unsupported
+          // effort remains ineligible.
+          const thinking =
+            thinkingOverrides?.[tier] ??
+            ((config.thinkingExplicit ?? config.thinking !== undefined)
+              ? primary.thinking
+              : ownConfig?.reasoning === false || !model?.reasoning
+                ? 'off'
+                : primary.thinking);
+          const pair = { tier, model: `${provider}/${modelId}`, thinking };
+          return validateRoutePair(
+            pair,
+            findModel,
+            imageAttached,
+            ownConfig?.reasoning === false
+              ? []
+              : index === 0
+                ? (config.thinkingLevels ?? config.resolvedThinkingLevels)
+                : ownConfig?.thinkingLevels,
+          )
+            ? [pair]
+            : [];
+        } catch {
+          return [];
+        }
+      })
+      .filter(
+        (pair, index, pairs) =>
+          pairs.findIndex((other) => other.model === pair.model) === index,
+      );
+  });
 
-  if (pinnedTier) {
-    phase = phaseForTier(pinnedTier);
-    tier = pinnedTier;
-    reasoning = `Pinned to ${pinnedTier} tier via /router-pin.`;
-  } else {
-    // Check custom rules first
-    if (rules) {
-      let highestTier: RouterTier | undefined;
-      let winningRule: RoutingRule | undefined;
-      const tierRank: Record<RouterTier, number> = {
-        low: 1,
-        medium: 2,
-        high: 3,
-      };
+/**
+ * Keep at least one configured route usable for each input kind when a
+ * thinking override is accepted. This prevents an override from silently
+ * removing all generation options while still allowing partial profiles and
+ * explicit pins to fail at their normal capability check.
+ */
+export const preservesRouteCoverage = (
+  profile: RouterProfile,
+  findModel: (provider: string, modelId: string) => Model<Api> | undefined,
+  thinkingOverrides: RouterThinkingByTier,
+): boolean => {
+  for (const imageAttached of [false, true]) {
+    const configured = availableRoutePairs(profile, findModel, imageAttached);
+    const overridden = availableRoutePairs(
+      profile,
+      findModel,
+      imageAttached,
+      thinkingOverrides,
+    );
+    if (configured.length > 0 && overridden.length === 0) return false;
+  }
+  return [false, true].some(
+    (imageAttached) =>
+      availableRoutePairs(profile, findModel, imageAttached, thinkingOverrides)
+        .length > 0,
+  );
+};
 
-      for (const rule of rules) {
-        const matches = Array.isArray(rule.matches)
-          ? rule.matches
-          : [rule.matches];
-        const lowercaseMatches = matches.map((m) => m.toLowerCase());
-        if (containsAny(prompt, lowercaseMatches)) {
-          if (!highestTier || tierRank[rule.tier] > tierRank[highestTier]) {
-            highestTier = rule.tier;
-            winningRule = rule;
-          }
-        }
-      }
+export interface BaselineSelection {
+  pair: RoutePair;
+  reasonCode: 'baseline' | 'pinned' | 'budget';
+  isBudgetForced: boolean;
+}
 
-      if (winningRule && highestTier) {
-        tier = highestTier;
-        phase = phaseForTier(tier);
-        const matches = Array.isArray(winningRule.matches)
-          ? winningRule.matches
-          : [winningRule.matches];
-        reasoning =
-          winningRule.reason ??
-          `Matched custom routing rule for: ${matches.join(', ')}`;
-        isRuleMatched = true;
-      }
-    }
+const routeForTier = (
+  pairs: readonly RoutePair[],
+  tier: RouterTier,
+): RoutePair | undefined => pairs.find((pair) => pair.tier === tier);
 
-    if (!isRuleMatched) {
-      // Sticky phase adjustments
-      const highThreshold = Math.max(
-        40,
-        120 - (previousDecision?.phase === 'planning' ? phaseBias * 80 : 0),
-      );
-      const lowThreshold = Math.max(
-        4,
-        12 -
-          (previousDecision?.phase === 'implementation' ||
-          previousDecision?.phase === 'planning'
-            ? phaseBias * 8
-            : 0),
-      );
+const preferredOrder = (profile: RouterProfile): readonly RouterTier[] => {
+  const baseline = profile.baselineTier;
+  if (!baseline || !profile[baseline]) return BASELINE_TIER_ORDER;
+  return [baseline, ...BASELINE_TIER_ORDER.filter((tier) => tier !== baseline)];
+};
 
-      if (containsAny(prompt, explicitHighHints)) {
-        phase = 'planning';
-        tier = 'high';
-        reasoning =
-          'Detected an explicit request for deeper or higher-quality reasoning.';
-      } else if (containsAny(prompt, explicitLowHints)) {
-        phase = 'lightweight';
-        tier = 'low';
-        reasoning =
-          'Detected an explicit request for a faster or lighter response.';
-      } else if (containsAny(prompt, summaryKeywords)) {
-        phase = 'lightweight';
-        tier = 'low';
-        reasoning = 'Detected summary or lightweight transformation keywords.';
-      } else if (
-        containsAny(prompt, planningKeywords) ||
-        prompt.startsWith('why ') ||
-        wordCount >= highThreshold ||
-        multiLinePrompt
-      ) {
-        phase = 'planning';
-        tier = 'high';
-        reasoning =
-          previousDecision?.phase === 'planning'
-            ? 'Continued planning phase based on complexity or keywords.'
-            : 'Detected planning, broad analysis, or a high-complexity request.';
-      } else if (containsAny(prompt, implementationKeywords)) {
-        phase = 'implementation';
-        tier = 'medium';
-        reasoning =
-          'Detected implementation-oriented work with bounded execution scope.';
-      } else if (
-        containsAny(prompt, lookupKeywords) &&
-        wordCount <= 24 &&
-        toolResultCount === 0
-      ) {
-        phase = 'lightweight';
-        tier = 'low';
-        reasoning = 'Detected a short read-only lookup request.';
-      } else if (
-        previousDecision?.phase === 'planning' &&
-        toolResultCount === 0 &&
-        wordCount > lowThreshold
-      ) {
-        phase = 'planning';
-        tier = 'high';
-        reasoning =
-          'Kept the planning-phase bias because the conversation still looks exploratory.';
-      } else if (
-        toolResultCount > 0 ||
-        previousDecision?.phase === 'implementation' ||
-        recentConversation.includes('plan:')
-      ) {
-        phase = 'implementation';
-        tier = 'medium';
-        reasoning =
-          'Detected active implementation work from prior tools or recent plan execution context.';
-      } else if (wordCount <= lowThreshold) {
-        phase = 'lightweight';
-        tier = 'low';
-        reasoning = 'Detected a short bounded request.';
-      }
-    }
+const chooseFromOrder = (
+  pairs: readonly RoutePair[],
+  order: readonly RouterTier[],
+): RoutePair | undefined => {
+  for (const tier of order) {
+    const pair = routeForTier(pairs, tier);
+    if (pair) return pair;
   }
+  return undefined;
+};
 
-  let isBudgetForced = false;
-  if (isBudgetExceeded && tier === 'high') {
-    tier = 'medium';
-    phase = 'implementation';
-    reasoning = `Budget exceeded. Downgraded from high to medium tier. (Original: ${reasoning})`;
-    isBudgetForced = true;
+/**
+ * Select the local route without inspecting prompt text. Eligibility has
+ * already been filtered by the registry/input/effort boundary.
+ */
+export const selectBaselineRoute = (
+  profileName: string,
+  profile: RouterProfile,
+  pairs: readonly RoutePair[],
+  pinnedTier?: RouterTier,
+  isBudgetExceeded = false,
+): BaselineSelection => {
+  if (pinnedTier) {
+    const pair = routeForTier(pairs, pinnedTier);
+    if (!pair) {
+      throw new Error(
+        `Pinned tier "${pinnedTier}" for profile "${profileName}" has no eligible model for the current input and thinking level.`,
+      );
+    }
+    return { pair, reasonCode: 'pinned', isBudgetForced: false };
   }
 
-  // Resolve to nearest available tier if the selected tier is disabled
-  const resolvedTier =
-    isBudgetForced && !profile.medium && profile.low
-      ? 'low'
-      : resolveAvailableTier(profile, tier);
-  if (resolvedTier !== tier) {
-    reasoning = `Resolved from ${tier} to ${resolvedTier} tier (${tier} tier is not configured). Original: ${reasoning}`;
-    phase = phaseForTier(resolvedTier);
-    tier = resolvedTier;
+  const order = preferredOrder(profile);
+  if (isBudgetExceeded) {
+    const budgetOrder = order.filter(
+      (tier) => tier === 'medium' || tier === 'low' || tier === 'micro',
+    );
+    const budgetPair = chooseFromOrder(pairs, budgetOrder);
+    if (budgetPair) {
+      return { pair: budgetPair, reasonCode: 'budget', isBudgetForced: true };
+    }
+    const configuredBaseline = chooseFromOrder(pairs, order);
+    if (configuredBaseline) {
+      return {
+        pair: configuredBaseline,
+        reasonCode: 'budget',
+        isBudgetForced: false,
+      };
+    }
+  } else {
+    const baseline = chooseFromOrder(pairs, order);
+    if (baseline)
+      return { pair: baseline, reasonCode: 'baseline', isBudgetForced: false };
   }
 
-  const decision = buildRoutingDecision(
-    profileName,
-    profile,
-    tier,
-    phase,
-    reasoning,
-    thinkingOverrides,
-    false,
+  throw new Error(
+    `No eligible route for profile "${profileName}": no configured model is available for the current input and thinking level.`,
   );
-  decision.isRuleMatched = isRuleMatched;
-  decision.isBudgetForced = isBudgetForced;
-  return decision;
+};
+
+export const primaryRoutePairs = (
+  profile: RouterProfile,
+  pairs: readonly RoutePair[],
+): RoutePair[] =>
+  BASELINE_TIER_ORDER.flatMap((tier) => {
+    // Keep the effective effort already validated against the live registry.
+    const primary = pairs.find(
+      (pair) => pair.tier === tier && pair.model === profile[tier]?.model,
+    );
+    return primary ? [primary] : [];
+  });
+
+export const decisionForPair = (
+  profile: string,
+  pair: RoutePair,
+  reasonCode: RoutingReasonCode,
+): RoutingDecision => {
+  const { provider, modelId } = parseCanonicalModelRef(pair.model);
+  return {
+    profile,
+    tier: pair.tier,
+    phase: phaseForTier(pair.tier),
+    targetProvider: provider,
+    targetModelId: modelId,
+    targetLabel: pair.model,
+    thinking: pair.thinking,
+    reasonCode,
+    timestamp: Date.now(),
+  };
 };

package/extensions/state.ts

@@ -14,6 +14,7 @@ import type {
   RouterPinByProfile,
   RoutingDecision,
 } from './types';
+import { isAdvisorOutcome, isRoutingReasonCode } from './types';
 
 const LAST_PROFILE_STATE_FILE = 'model-router-state.json';
 
@@ -30,20 +31,34 @@ 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)) &&
+  (value.advisor === undefined || isAdvisorOutcome(value.advisor)) &&
+  ['isClassifier', 'isFallback', 'isBudgetForced'].every(
     (key) => value[key] === undefined || typeof value[key] === 'boolean',
   );
 const isMap = (value: unknown, validate: (entry: unknown) => boolean) =>
@@ -128,6 +143,36 @@ export const isRouterPersistedState = (
   );
 };
 
+// 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,
+  advisor: isAdvisorOutcome(decision.advisor) ? decision.advisor : undefined,
+  thinking: decision.thinking,
+  timestamp: decision.timestamp,
+  isClassifier: decision.isClassifier,
+  isFallback: decision.isFallback,
+  isBudgetForced: decision.isBudgetForced,
+});
+
 export const buildPersistedState = ({
   routerEnabled,
   selectedProfile,
@@ -154,9 +199,9 @@ export const buildPersistedState = ({
     thinkingByProfile: { ...thinkingByProfile },
     debugEnabled,
     widgetEnabled,
-    debugHistory,
+    debugHistory: debugHistory.map(snapshotDecision),
     lastPhase: lastDecision?.phase,
-    lastDecision,
+    lastDecision: lastDecision ? snapshotDecision(lastDecision) : undefined,
     lastNonRouterModel,
     accumulatedCost,
     timestamp: Date.now(),