pi-smart-router 0.1.0

package/src/domain/pipeline/safe-default.ts

@@ -0,0 +1,70 @@
+/**
+ * Safe cloud default — FR-022 fallback selector.
+ *
+ * Selects the first healthy economical-cloud model from the fleet,
+ * falling back to frontier-cloud only when no economical model is available.
+ * Never throws; returns undefined only when the fleet is completely empty or unhealthy.
+ *
+ * SP-095: when a request is provided, only models that fit context are eligible.
+ */
+
+import type { ModelProfile, RoutingRequest } from '../types/index.js';
+import {
+  modelFitsContext,
+  resolveSafetyMargin,
+  type ContextFitConfig,
+} from '../routing/context-fit.js';
+
+export interface SafeCloudDefaultOptions {
+  readonly request?: RoutingRequest;
+  readonly contextFitConfig?: ContextFitConfig;
+}
+
+function isHealthy(model: ModelProfile): boolean {
+  return model.healthy !== false;
+}
+
+function fitsWhenRequired(
+  model: ModelProfile,
+  request: RoutingRequest | undefined,
+  config: ContextFitConfig | undefined,
+): boolean {
+  if (!request) {
+    return true;
+  }
+
+  const estimatedInputTokens =
+    request.estimated_input_tokens ?? request.prompt_text.length;
+  return modelFitsContext(model, estimatedInputTokens, resolveSafetyMargin(config));
+}
+
+/**
+ * Select a safe cloud default model from the fleet catalog.
+ *
+ * Priority order:
+ *   1. First healthy economical-cloud model (context-fit aware when request provided)
+ *   2. First healthy frontier-cloud model (fallback)
+ *   3. undefined (no viable model)
+ */
+export function safeCloudDefault(
+  models: readonly ModelProfile[],
+  options?: SafeCloudDefaultOptions,
+): ModelProfile | undefined {
+  const request = options?.request;
+  const config = options?.contextFitConfig;
+
+  const economical = models.find(
+    (model) =>
+      model.tier === 'economical-cloud' &&
+      isHealthy(model) &&
+      fitsWhenRequired(model, request, config),
+  );
+  if (economical) return economical;
+
+  return models.find(
+    (model) =>
+      model.tier === 'frontier-cloud' &&
+      isHealthy(model) &&
+      fitsWhenRequired(model, request, config),
+  );
+}

package/src/domain/refactor-guardrails.ts

@@ -0,0 +1,202 @@
+/**
+ * Epic refactor guardrails — SP-083.
+ *
+ * Detects large refactoring workloads and emits spine-decomposition,
+ * test-gate, and frontier-routing policies. Inert for normal requests —
+ * callers treat `is_epic: false` as a no-op.
+ */
+
+import { cyclomaticScan } from './triage/triage-engine.js';
+import type { RoutingRequest, Tier } from './types/index.js';
+
+export const EPIC_REFACTOR_DETECTED = 'epic_refactor_detected' as const;
+export const EPIC_REFACTOR_NOT_DETECTED = 'epic_refactor_not_detected' as const;
+
+export const EPIC_REFACTOR_RECOMMENDED_TIER: Tier = 'frontier-cloud';
+
+export type EpicRefactorGuardrailKind =
+  | 'spine_decomposition'
+  | 'test_gate'
+  | 'frontier_routing';
+
+export const EPIC_REFACTOR_GUARDRAILS: readonly EpicRefactorGuardrailKind[] = [
+  'spine_decomposition',
+  'test_gate',
+  'frontier_routing',
+];
+
+export interface EpicRefactorScopeSignals {
+  readonly epic_keyword_hits: number;
+  readonly file_path_mentions: number;
+  readonly cyclomatic_score: number;
+  readonly planning_turn: boolean;
+}
+
+export interface EpicRefactorGuardrailEvaluation {
+  readonly is_epic: boolean;
+  readonly reason_code:
+    | typeof EPIC_REFACTOR_DETECTED
+    | typeof EPIC_REFACTOR_NOT_DETECTED;
+  readonly guardrails: readonly EpicRefactorGuardrailKind[];
+  readonly recommended_tier?: Tier;
+  readonly signals: EpicRefactorScopeSignals;
+}
+
+export interface EpicRefactorGuardrailConfig {
+  /** Minimum epic-keyword hits when paired with other scope signals. Default 1. */
+  readonly minKeywordHits?: number;
+  /** File-path mentions required with a keyword hit. Default 3. */
+  readonly minFilePathMentions?: number;
+  /** Cyclomatic score required with planning turn + keyword. Default 15. */
+  readonly minCyclomaticScore?: number;
+  /** Keyword hits that alone qualify as epic. Default 2. */
+  readonly standaloneKeywordHits?: number;
+}
+
+const DEFAULT_CONFIG: Required<EpicRefactorGuardrailConfig> = {
+  minKeywordHits: 1,
+  minFilePathMentions: 3,
+  minCyclomaticScore: 15,
+  standaloneKeywordHits: 2,
+};
+
+const EPIC_KEYWORDS: readonly string[] = [
+  'epic refactor',
+  'god file',
+  'god object',
+  'god class',
+  'decompose',
+  'decomposition',
+  'large refactor',
+  'large-scale refactor',
+  'mass refactor',
+  'restructure',
+  'split module',
+  'extract module',
+  'break up',
+  'monolith',
+  'cross-cutting',
+  'wide-reaching',
+  'rename across',
+  'move across',
+  'refactor entire',
+  'refactor whole',
+];
+
+const STRONG_EPIC_PHRASES: readonly RegExp[] = [
+  /\bepic\s+refactor\b/i,
+  /\bgod\s+(?:file|object|class)\b/i,
+  /\bdecompos(?:e|ition)\b/i,
+];
+
+const RE_FILE_PATH =
+  /\b(?:[\w@.-]+\/)+[\w@.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|rb|php|cs|vue|svelte)\b/gi;
+
+const RE_BARE_FILE =
+  /\b[\w@.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|kt|swift|rb|php|cs|vue|svelte)\b/gi;
+
+function countKeywordHits(text: string): number {
+  const lower = text.toLowerCase();
+  let hits = 0;
+
+  for (const keyword of EPIC_KEYWORDS) {
+    if (lower.includes(keyword)) {
+      hits += 1;
+    }
+  }
+
+  for (const pattern of STRONG_EPIC_PHRASES) {
+    if (pattern.test(text)) {
+      hits += 1;
+    }
+  }
+
+  return hits;
+}
+
+function countFilePathMentions(text: string): number {
+  const paths = new Set<string>();
+
+  for (const match of text.matchAll(RE_FILE_PATH)) {
+    paths.add(match[0]!.toLowerCase());
+  }
+
+  for (const match of text.matchAll(RE_BARE_FILE)) {
+    paths.add(match[0]!.toLowerCase());
+  }
+
+  return paths.size;
+}
+
+export function collectEpicRefactorScopeSignals(
+  request: RoutingRequest,
+): EpicRefactorScopeSignals {
+  const text = request.prompt_text;
+  return {
+    epic_keyword_hits: countKeywordHits(text),
+    file_path_mentions: countFilePathMentions(text),
+    cyclomatic_score: cyclomaticScan(text),
+    planning_turn: request.turn_type === 'planning',
+  };
+}
+
+/**
+ * Returns true when scope signals indicate an epic refactor workload.
+ * Conservative thresholds keep normal routing and small edits unaffected.
+ */
+export function isEpicRefactorScope(
+  signals: EpicRefactorScopeSignals,
+  config?: EpicRefactorGuardrailConfig,
+): boolean {
+  const resolved = { ...DEFAULT_CONFIG, ...config };
+
+  if (signals.epic_keyword_hits >= resolved.standaloneKeywordHits) {
+    return true;
+  }
+
+  if (
+    signals.epic_keyword_hits >= resolved.minKeywordHits &&
+    signals.file_path_mentions >= resolved.minFilePathMentions
+  ) {
+    return true;
+  }
+
+  if (
+    signals.planning_turn &&
+    signals.epic_keyword_hits >= resolved.minKeywordHits &&
+    signals.cyclomatic_score >= resolved.minCyclomaticScore
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Evaluate epic-refactor guardrails for a routing request.
+ * Non-epic requests return empty guardrails and no tier override.
+ */
+export function evaluateEpicRefactorGuardrails(
+  request: RoutingRequest,
+  config?: EpicRefactorGuardrailConfig,
+): EpicRefactorGuardrailEvaluation {
+  const signals = collectEpicRefactorScopeSignals(request);
+  const is_epic = isEpicRefactorScope(signals, config);
+
+  if (!is_epic) {
+    return {
+      is_epic: false,
+      reason_code: EPIC_REFACTOR_NOT_DETECTED,
+      guardrails: [],
+      signals,
+    };
+  }
+
+  return {
+    is_epic: true,
+    reason_code: EPIC_REFACTOR_DETECTED,
+    guardrails: EPIC_REFACTOR_GUARDRAILS,
+    recommended_tier: EPIC_REFACTOR_RECOMMENDED_TIER,
+    signals,
+  };
+}

package/src/domain/routing/context-fit.ts

@@ -0,0 +1,221 @@
+/**
+ * Context-fit gate — SP-093, overflow fallback — SP-095.
+ *
+ * Filters fleet models whose context window cannot accommodate the estimated
+ * input token count (with a configurable safety margin).
+ */
+
+import type {
+  CandidateScore,
+  ModelProfile,
+  RoutingRequest,
+} from '../types/index.js';
+import { selectLowestCostModel } from '../pinning/sub-route-policy.js';
+
+export const CONTEXT_FIT_EXCEEDED = 'context_fit_exceeded' as const;
+
+export const CONTEXT_OVERFLOW_SAME_PROVIDER_FALLBACK =
+  'context_overflow_same_provider_fallback' as const;
+export const CONTEXT_OVERFLOW_FRONTIER_FALLBACK =
+  'context_overflow_frontier_fallback' as const;
+export const CONTEXT_OVERFLOW_NO_FIT = 'context_overflow_no_fit' as const;
+
+export const DEFAULT_CONTEXT_FIT_SAFETY_MARGIN = 0.9;
+
+export const CONTEXT_FIT_SAFETY_MARGIN_ENV = 'CONTEXT_FIT_SAFETY_MARGIN';
+
+export interface ContextFitConfig {
+  /** Fraction of max_input_tokens treated as usable (default 0.90). */
+  readonly safetyMargin?: number;
+}
+
+export interface ContextFitFilterResult {
+  readonly effectiveFleet: readonly ModelProfile[];
+  readonly rejected: readonly CandidateScore[];
+}
+
+export interface ContextOverflowFallbackResult {
+  readonly kind: 'selected' | 'no_fit';
+  readonly model?: ModelProfile;
+  readonly reasonCode:
+    | typeof CONTEXT_OVERFLOW_SAME_PROVIDER_FALLBACK
+    | typeof CONTEXT_OVERFLOW_FRONTIER_FALLBACK
+    | typeof CONTEXT_OVERFLOW_NO_FIT;
+}
+
+function resolveEstimatedInputTokens(request: RoutingRequest): number {
+  return request.estimated_input_tokens ?? request.prompt_text.length;
+}
+
+export function resolveSafetyMargin(config?: ContextFitConfig): number {
+  if (config?.safetyMargin !== undefined) {
+    return config.safetyMargin;
+  }
+
+  const raw = process.env[CONTEXT_FIT_SAFETY_MARGIN_ENV];
+  if (raw === undefined || raw.trim() === '') {
+    return DEFAULT_CONTEXT_FIT_SAFETY_MARGIN;
+  }
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1) {
+    return DEFAULT_CONTEXT_FIT_SAFETY_MARGIN;
+  }
+
+  return parsed;
+}
+
+export function modelFitsContext(
+  profile: ModelProfile,
+  estimatedInputTokens: number,
+  safetyMargin: number,
+): boolean {
+  const maxInput = profile.limits?.max_input_tokens;
+  if (maxInput === undefined) {
+    return true;
+  }
+
+  const effectiveLimit = Math.floor(maxInput * safetyMargin);
+  return estimatedInputTokens <= effectiveLimit;
+}
+
+function isHealthy(model: ModelProfile): boolean {
+  return model.healthy !== false;
+}
+
+/**
+ * Select the model with the largest declared context window.
+ * Models without declared limits sort last (treated as unknown / unbounded).
+ */
+export function selectLargestWindowModel(
+  candidates: readonly ModelProfile[],
+): ModelProfile | undefined {
+  let best: ModelProfile | undefined;
+  let bestWindow = -1;
+
+  for (const model of candidates) {
+    if (!isHealthy(model)) continue;
+    const window = model.limits?.max_input_tokens ?? Number.MAX_SAFE_INTEGER;
+    if (window > bestWindow) {
+      bestWindow = window;
+      best = model;
+    }
+  }
+
+  return best;
+}
+
+/**
+ * SP-095: escalate when economical/pinned models cannot fit context.
+ *
+ * 1. Same-provider largest-fit model
+ * 2. Cheapest frontier model that fits
+ * 3. Structured no-fit (never dispatch undersized)
+ */
+export function resolveContextOverflowFallback(
+  fleet: readonly ModelProfile[],
+  request: RoutingRequest,
+  preferredProvider: string | null,
+  config?: ContextFitConfig,
+): ContextOverflowFallbackResult {
+  const estimatedInputTokens = resolveEstimatedInputTokens(request);
+  const safetyMargin = resolveSafetyMargin(config);
+  const fits = (model: ModelProfile): boolean =>
+    modelFitsContext(model, estimatedInputTokens, safetyMargin);
+
+  if (preferredProvider) {
+    const sameProviderCandidates = fleet.filter(
+      (model) => model.provider === preferredProvider && fits(model),
+    );
+    const sameProviderModel = selectLargestWindowModel(sameProviderCandidates);
+    if (sameProviderModel) {
+      return {
+        kind: 'selected',
+        model: sameProviderModel,
+        reasonCode: CONTEXT_OVERFLOW_SAME_PROVIDER_FALLBACK,
+      };
+    }
+  }
+
+  const frontierCandidates = fleet.filter(
+    (model) => model.tier === 'frontier-cloud' && fits(model),
+  );
+  const frontierModel = selectLowestCostModel(frontierCandidates);
+  if (frontierModel) {
+    return {
+      kind: 'selected',
+      model: frontierModel,
+      reasonCode: CONTEXT_OVERFLOW_FRONTIER_FALLBACK,
+    };
+  }
+
+  return {
+    kind: 'no_fit',
+    reasonCode: CONTEXT_OVERFLOW_NO_FIT,
+  };
+}
+
+/**
+ * True when economical models were rejected for context fit and none remain
+ * in the post-filter fleet.
+ */
+export function needsContextOverflowFallback(
+  activeFleet: readonly ModelProfile[],
+  rejected: readonly CandidateScore[],
+  fullFleet: readonly ModelProfile[],
+): boolean {
+  if (rejected.length === 0) {
+    return false;
+  }
+
+  const hasActiveEconomical = activeFleet.some(
+    (model) => model.tier === 'economical-cloud' && isHealthy(model),
+  );
+  if (hasActiveEconomical) {
+    return false;
+  }
+
+  return rejected.some((candidate) => {
+    const profile = fullFleet.find((model) => model.id === candidate.model_id);
+    return profile?.tier === 'economical-cloud';
+  });
+}
+
+/**
+ * Remove fleet entries whose max_input_tokens cannot fit estimated_input_tokens
+ * at the given safety margin. Honors `force_model_id` by leaving fleet unchanged.
+ * Models without declared limits are retained (unknown window).
+ */
+export function filterFleetByContextFit(
+  fleet: readonly ModelProfile[],
+  request: RoutingRequest,
+  config?: ContextFitConfig,
+): ContextFitFilterResult {
+  if (request.force_model_id) {
+    return { effectiveFleet: fleet, rejected: [] };
+  }
+
+  const estimatedInputTokens = resolveEstimatedInputTokens(request);
+  const safetyMargin = resolveSafetyMargin(config);
+
+  const effectiveFleet: ModelProfile[] = [];
+  const rejected: CandidateScore[] = [];
+
+  for (const profile of fleet) {
+    if (modelFitsContext(profile, estimatedInputTokens, safetyMargin)) {
+      effectiveFleet.push(profile);
+      continue;
+    }
+
+    const maxInput = profile.limits!.max_input_tokens!;
+    const effectiveLimit = Math.floor(maxInput * safetyMargin);
+    rejected.push({
+      model_id: profile.id,
+      score: 0,
+      shortfall: estimatedInputTokens - effectiveLimit,
+      rejected_reason: CONTEXT_FIT_EXCEEDED,
+    });
+  }
+
+  return { effectiveFleet, rejected };
+}