pi-smart-router 0.1.0

package/src/domain/pinning/loop-escalation.ts

@@ -0,0 +1,181 @@
+/**
+ * Loop escalation — FR-014, FR-008 rule #3.
+ *
+ * Detects bounded repeated identical tool failures and signals
+ * session pin escalation to a frontier-capable tier.
+ *
+ * Escalation fires once per session; no tier oscillation (FR-008).
+ * Threshold defaults to 3 identical tool failures (operator configurable).
+ *
+ * Design: pure evaluation function — caller (pipeline stage) is
+ * responsible for applying pin state updates via SessionPinner.
+ */
+
+import type { ModelProfile, RoutingRequest, SessionPin } from '../types/index.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface LoopEscalationConfig {
+  readonly threshold: number;
+}
+
+export interface LoopEscalationResult {
+  readonly shouldEscalate: boolean;
+  readonly updatedPin: SessionPin | null;
+  readonly escalationTarget: ModelProfile | null;
+  readonly reason: string;
+}
+
+// ─── Failure signature extraction ─────────────────────────────────────────────
+
+const FAILURE_PATTERNS = [
+  'error',
+  'fail',
+  'exception',
+  'timed out',
+  'timeout',
+  'econnrefused',
+  'enotfound',
+  'econnreset',
+  'epipe',
+] as const;
+
+/**
+ * Extract a tool-failure signature from the request's messages.
+ * Returns null when the request does not carry a tool failure.
+ *
+ * Only inspects tool_result turns — other turn types cannot
+ * carry observational failure signals (FR-014: no post-generation judging).
+ */
+export function extractToolFailureSignature(request: RoutingRequest): string | null {
+  const msgs = request.messages;
+  if (!msgs || msgs.length === 0) return null;
+
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const msg = msgs[i]!;
+    if (msg.role === 'tool') {
+      if (looksLikeFailure(msg.content)) {
+        return computeSignature(msg.content);
+      }
+      return null;
+    }
+  }
+  return null;
+}
+
+function looksLikeFailure(content: string): boolean {
+  const lower = content.toLowerCase();
+  return FAILURE_PATTERNS.some((p) => lower.includes(p));
+}
+
+/** Deterministic djb2 hash of normalised error content. */
+function computeSignature(content: string): string {
+  const normalized = content.trim().slice(0, 256).toLowerCase();
+  let h = 5381;
+  for (let i = 0; i < normalized.length; i++) {
+    h = ((h << 5) + h + normalized.charCodeAt(i)) | 0;
+  }
+  return `tf:${(h >>> 0).toString(16)}`;
+}
+
+// ─── Evaluation ───────────────────────────────────────────────────────────────
+
+/**
+ * Evaluate whether the session should escalate to a higher tier.
+ *
+ * Pure function — does not mutate pin state. Returns `updatedPin`
+ * when the caller should persist new failure-tracking state.
+ *
+ * Caller applies updates via `SessionPinner.loadPin()`, and on
+ * escalation via `breakPin()` + `recordPin()`.
+ */
+export function evaluateLoopEscalation(
+  pin: SessionPin | null,
+  request: RoutingRequest,
+  fleet: readonly ModelProfile[],
+  config: LoopEscalationConfig,
+): LoopEscalationResult {
+  if (!pin) {
+    return noEscalation('no_pin');
+  }
+
+  if (pin.pin_reason === 'loop_escalation') {
+    return noEscalation('already_escalated');
+  }
+
+  if (request.turn_type !== 'tool_result') {
+    return noEscalation('not_tool_result');
+  }
+
+  const signature = extractToolFailureSignature(request);
+
+  if (!signature) {
+    if (pin.consecutive_tool_failures > 0) {
+      return {
+        shouldEscalate: false,
+        updatedPin: {
+          ...pin,
+          consecutive_tool_failures: 0,
+          last_tool_failure_signature: null,
+          updated_at: new Date().toISOString(),
+        },
+        escalationTarget: null,
+        reason: 'success_reset',
+      };
+    }
+    return noEscalation('no_failure');
+  }
+
+  const isIdentical = pin.last_tool_failure_signature === signature;
+  const newCount = isIdentical ? pin.consecutive_tool_failures + 1 : 1;
+
+  const updated: SessionPin = {
+    ...pin,
+    consecutive_tool_failures: newCount,
+    last_tool_failure_signature: signature,
+    updated_at: new Date().toISOString(),
+  };
+
+  if (newCount >= config.threshold) {
+    const target = selectEscalationTarget(fleet, pin.pinned_model_id);
+    if (target) {
+      return {
+        shouldEscalate: true,
+        updatedPin: updated,
+        escalationTarget: target,
+        reason: 'threshold_exceeded',
+      };
+    }
+    return {
+      shouldEscalate: false,
+      updatedPin: updated,
+      escalationTarget: null,
+      reason: 'no_frontier_available',
+    };
+  }
+
+  return {
+    shouldEscalate: false,
+    updatedPin: updated,
+    escalationTarget: null,
+    reason: 'below_threshold',
+  };
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function noEscalation(reason: string): LoopEscalationResult {
+  return { shouldEscalate: false, updatedPin: null, escalationTarget: null, reason };
+}
+
+/** Select the best healthy frontier-cloud model that differs from the current pin. */
+function selectEscalationTarget(
+  fleet: readonly ModelProfile[],
+  currentModelId: string,
+): ModelProfile | null {
+  return (
+    fleet.find(
+      (m) => m.tier === 'frontier-cloud' && m.id !== currentModelId && m.healthy !== false,
+    ) ?? null
+  );
+}

package/src/domain/pinning/session-pinner.ts

@@ -0,0 +1,388 @@
+/**
+ * Session pinner — FR-006, FR-007, FR-008, FR-024.
+ *
+ * Pins a session to one model after the initial routing decision.
+ * Pin holds across subsequent turns until a qualified break event.
+ *
+ * Break rules (FR-008, exhaustive):
+ *   1. History compaction
+ *   2. Context overflow (estimated tokens exceed pinned model window)
+ *   3. Explicit operator/user override
+ *   4. Qualified loop escalation (threshold managed externally)
+ *   5. Cache-warmup economics when a cross-provider switch is proposed
+ *
+ * Sub-routing (FR-024): tool-result turns below the payload threshold
+ * may use an economical model on the same provider without breaking the pin.
+ */
+
+import type {
+  ModelProfile,
+  PinReason,
+  RoutingRequest,
+  SessionPin,
+} from '../types/index.js';
+import type { StorePort } from '../types/store-port.js';
+import {
+  evaluateCacheEconomics,
+  type CacheEconomicsConfig,
+} from './cache-economics.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type PinAction = 'use_pin' | 'sub_route' | 'break' | 'no_pin';
+
+export interface PinLookupResult {
+  readonly action: PinAction;
+  readonly pinnedModel?: ModelProfile;
+  readonly subRouteModel?: ModelProfile;
+  readonly breakReason?: PinReason;
+}
+
+export interface SessionPinnerConfig {
+  /** FR-024: max payload size (bytes or token estimate) for sub-routing. Default 2048. */
+  readonly toolResultSizeThreshold?: number;
+  /** Optional persistence — pins survive process restart when set. */
+  readonly store?: StorePort;
+  /** FR-008 rule #4: cache-warmup economics thresholds. */
+  readonly cacheEconomicsConfig?: CacheEconomicsConfig;
+  /**
+   * Break pin when estimated input tokens exceed the pinned model's
+   * max_input_tokens multiplied by this margin. Default 0.90.
+   */
+  readonly contextOverflowSafetyMargin?: number;
+}
+
+// ─── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_TOOL_RESULT_SIZE_THRESHOLD = 2048;
+const DEFAULT_CONTEXT_OVERFLOW_SAFETY_MARGIN = 0.9;
+
+// ─── SessionPinner ────────────────────────────────────────────────────────────
+
+export class SessionPinner {
+  private readonly pins = new Map<string, SessionPin>();
+  private readonly toolResultSizeThreshold: number;
+  private readonly store: StorePort | undefined;
+  private readonly cacheEconomicsConfig: CacheEconomicsConfig | undefined;
+  private readonly contextOverflowSafetyMargin: number;
+
+  constructor(config?: SessionPinnerConfig) {
+    this.toolResultSizeThreshold =
+      config?.toolResultSizeThreshold ?? DEFAULT_TOOL_RESULT_SIZE_THRESHOLD;
+    this.store = config?.store;
+    this.cacheEconomicsConfig = config?.cacheEconomicsConfig;
+    this.contextOverflowSafetyMargin =
+      config?.contextOverflowSafetyMargin ?? DEFAULT_CONTEXT_OVERFLOW_SAFETY_MARGIN;
+  }
+
+  /**
+   * Hydrate in-memory pin state for a session from persistent storage.
+   * Call on session start after a pi restart so lookupPin stays synchronous.
+   */
+  async restoreSessionPin(sessionId: string): Promise<void> {
+    if (!this.store) {
+      return;
+    }
+
+    const pin = await this.store.getSessionPin(sessionId);
+    if (pin) {
+      this.pins.set(sessionId, pin);
+    }
+  }
+
+  /**
+   * Synchronous pin lookup — must complete in <1ms.
+   * All data is in-memory (Map); no I/O.
+   */
+  lookupPin(
+    request: RoutingRequest,
+    fleet: readonly ModelProfile[],
+  ): PinLookupResult {
+    const pin = this.pins.get(request.session_id);
+
+    if (!pin) {
+      return { action: 'no_pin' };
+    }
+
+    // ── Break rule evaluation (FR-008) ──────────────────────────────────────
+
+    const breakResult = this.evaluateBreakRules(request, pin, fleet);
+    if (breakResult) {
+      return breakResult;
+    }
+
+    // ── Sub-routing (FR-024) ────────────────────────────────────────────────
+
+    const subRouteResult = this.evaluateSubRouting(request, pin, fleet);
+    if (subRouteResult) {
+      return subRouteResult;
+    }
+
+    // ── Default: use pinned model (FR-006, FR-007) ──────────────────────────
+
+    const pinnedModel = fleet.find(
+      (m) => m.id === pin.pinned_model_id && m.healthy !== false,
+    );
+
+    if (!pinnedModel) {
+      this.breakPin(request.session_id);
+      return { action: 'no_pin' };
+    }
+
+    return { action: 'use_pin', pinnedModel };
+  }
+
+  /**
+   * Create or update a session pin after a routing decision.
+   */
+  recordPin(
+    sessionId: string,
+    modelId: string,
+    reason: PinReason,
+  ): SessionPin {
+    const now = new Date().toISOString();
+    const existing = this.pins.get(sessionId);
+
+    const pin: SessionPin = {
+      session_id: sessionId,
+      pinned_model_id: modelId,
+      pin_reason: reason,
+      has_ever_switched: existing
+        ? existing.pinned_model_id !== modelId || existing.has_ever_switched
+        : false,
+      consecutive_upstream_errors: 0,
+      consecutive_tool_failures: existing?.consecutive_tool_failures ?? 0,
+      last_tool_failure_signature: existing?.last_tool_failure_signature ?? null,
+      created_at: existing?.created_at ?? now,
+      updated_at: now,
+    };
+
+    this.pins.set(sessionId, pin);
+    this.persistPin(pin);
+    return pin;
+  }
+
+  /**
+   * Delete a session pin — used by loop escalation or external callers.
+   */
+  breakPin(sessionId: string): void {
+    this.pins.delete(sessionId);
+    this.deletePersistedPin(sessionId);
+  }
+
+  /**
+   * Hydrate a pin from persistent storage (e.g. SQLite restore).
+   */
+  loadPin(pin: SessionPin): void {
+    this.pins.set(pin.session_id, pin);
+    this.persistPin(pin);
+  }
+
+  /**
+   * Read-only access to the current pin (telemetry, inspection).
+   */
+  getPin(sessionId: string): SessionPin | null {
+    return this.pins.get(sessionId) ?? null;
+  }
+
+  // ─── Break rules (FR-008) ───────────────────────────────────────────────────
+
+  private evaluateBreakRules(
+    request: RoutingRequest,
+    pin: SessionPin,
+    fleet: readonly ModelProfile[],
+  ): PinLookupResult | null {
+    // 1. History compaction → break pin, allow full re-route
+    if (request.compaction_flag) {
+      this.breakPin(request.session_id);
+      return { action: 'break', breakReason: 'compaction' };
+    }
+
+    // 2. Context overflow → break pin when input exceeds pinned model window
+    const overflowResult = this.evaluateContextOverflowBreak(
+      request,
+      pin,
+      fleet,
+    );
+    if (overflowResult) {
+      return overflowResult;
+    }
+
+    // 3. Explicit operator / user override → pin to forced model
+    if (request.force_model_id) {
+      return this.handleForceOverride(request, pin, fleet);
+    }
+
+    // 4. Loop escalation — threshold tracking is on the pin record;
+    //    the loop_escalation pipeline stage calls breakPin() externally
+    //    when the threshold fires. No evaluation here beyond what the
+    //    pin record already reflects (consecutive_tool_failures).
+
+    // 5. Cache-warmup economics (FR-008 rule #4)
+    const cacheEconomicsResult = this.evaluateCacheEconomicsBreak(
+      request,
+      pin,
+      fleet,
+    );
+    if (cacheEconomicsResult) {
+      return cacheEconomicsResult;
+    }
+
+    return null;
+  }
+
+  private evaluateContextOverflowBreak(
+    request: RoutingRequest,
+    pin: SessionPin,
+    fleet: readonly ModelProfile[],
+  ): PinLookupResult | null {
+    const pinnedModel = fleet.find(
+      (m) => m.id === pin.pinned_model_id && m.healthy !== false,
+    );
+    const maxInputTokens = pinnedModel?.limits?.max_input_tokens;
+    if (!maxInputTokens) {
+      return null;
+    }
+
+    const tokenEstimate =
+      request.estimated_input_tokens ?? request.prompt_text.length;
+    const effectiveLimit = maxInputTokens * this.contextOverflowSafetyMargin;
+
+    if (tokenEstimate > effectiveLimit) {
+      this.breakPin(request.session_id);
+      return { action: 'break', breakReason: 'context_overflow' };
+    }
+
+    return null;
+  }
+
+  private evaluateCacheEconomicsBreak(
+    request: RoutingRequest,
+    pin: SessionPin,
+    fleet: readonly ModelProfile[],
+  ): PinLookupResult | null {
+    if (!request.candidate_model_id) {
+      return null;
+    }
+
+    if (request.candidate_model_id === pin.pinned_model_id) {
+      return null;
+    }
+
+    const pinnedModel = fleet.find(
+      (m) => m.id === pin.pinned_model_id && m.healthy !== false,
+    );
+    const candidate = fleet.find(
+      (m) => m.id === request.candidate_model_id && m.healthy !== false,
+    );
+
+    if (!pinnedModel || !candidate) {
+      return null;
+    }
+
+    if (pinnedModel.provider === candidate.provider) {
+      return null;
+    }
+
+    const tokenEstimate =
+      request.estimated_input_tokens ?? request.prompt_text.length;
+
+    const econ = evaluateCacheEconomics(
+      pin,
+      pinnedModel,
+      candidate,
+      tokenEstimate,
+      this.cacheEconomicsConfig,
+    );
+
+    if (econ.shouldSwitch) {
+      this.breakPin(request.session_id);
+      return { action: 'break', breakReason: 'cache_economics' };
+    }
+
+    return { action: 'use_pin', pinnedModel };
+  }
+
+  private handleForceOverride(
+    request: RoutingRequest,
+    _pin: SessionPin,
+    fleet: readonly ModelProfile[],
+  ): PinLookupResult {
+    const forced = fleet.find(
+      (m) => m.id === request.force_model_id && m.healthy !== false,
+    );
+
+    if (forced) {
+      this.recordPin(request.session_id, forced.id, 'user_forced');
+      return { action: 'use_pin', pinnedModel: forced };
+    }
+
+    // Forced model unavailable — break pin, allow re-route
+    this.breakPin(request.session_id);
+    return { action: 'break', breakReason: 'user_forced' };
+  }
+
+  // ─── Persistence (StorePort) ────────────────────────────────────────────────
+
+  private persistPin(pin: SessionPin): void {
+    if (!this.store) {
+      return;
+    }
+
+    void this.store.putSessionPin(pin).catch((error: unknown) => {
+      console.warn('Failed to persist session pin', { sessionId: pin.session_id, error });
+    });
+  }
+
+  private deletePersistedPin(sessionId: string): void {
+    if (!this.store) {
+      return;
+    }
+
+    void this.store.deleteSessionPin(sessionId).catch((error: unknown) => {
+      console.warn('Failed to delete persisted session pin', { sessionId, error });
+    });
+  }
+
+  // ─── Sub-routing (FR-024) ───────────────────────────────────────────────────
+
+  private evaluateSubRouting(
+    request: RoutingRequest,
+    pin: SessionPin,
+    fleet: readonly ModelProfile[],
+  ): PinLookupResult | null {
+    if (request.turn_type !== 'tool_result') {
+      return null;
+    }
+
+    const payloadSize =
+      request.estimated_input_tokens ?? request.prompt_text.length;
+
+    if (payloadSize > this.toolResultSizeThreshold) {
+      return null;
+    }
+
+    const pinnedModel = fleet.find((m) => m.id === pin.pinned_model_id);
+    if (!pinnedModel) {
+      return null;
+    }
+
+    const econModel = fleet.find(
+      (m) =>
+        m.tier === 'economical-cloud' &&
+        m.provider === pinnedModel.provider &&
+        m.id !== pin.pinned_model_id &&
+        m.healthy !== false,
+    );
+
+    if (!econModel) {
+      return null;
+    }
+
+    return {
+      action: 'sub_route',
+      subRouteModel: econModel,
+      pinnedModel,
+    };
+  }
+}

package/src/domain/pinning/sub-route-policy.ts

@@ -0,0 +1,119 @@
+/**
+ * Sub-route policy — FR-024.
+ *
+ * Pure policy function that evaluates whether a tool-result turn is
+ * eligible for same-provider economical sub-routing without breaking
+ * the session pin.
+ *
+ * Rules (FR-024, exhaustive):
+ *   1. Turn must be a tool_result.
+ *   2. Payload must be below the configurable size threshold (default 2 KB).
+ *   3. An economical-cloud model on the same provider as the pin must exist
+ *      and be healthy.
+ *   4. The economical model must not be the pinned model itself.
+ *
+ * When all conditions are met the caller may dispatch to the economical
+ * model. The session pin record is unchanged — the pin holds.
+ */
+
+import type { ModelProfile, RoutingRequest, SessionPin } from '../types/index.js';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type SubRouteReason =
+  | 'eligible'
+  | 'not_tool_result'
+  | 'payload_exceeds_threshold'
+  | 'pinned_model_not_in_fleet'
+  | 'no_same_provider_economical';
+
+export interface SubRouteEvaluation {
+  readonly eligible: boolean;
+  readonly subRouteModel?: ModelProfile;
+  readonly pinnedModel?: ModelProfile;
+  readonly reason: SubRouteReason;
+}
+
+export interface SubRoutePolicyConfig {
+  /** Max payload size (bytes or token estimate) for sub-routing. Default 2048. */
+  readonly sizeThreshold?: number;
+}
+
+// ─── Defaults ─────────────────────────────────────────────────────────────────
+
+const DEFAULT_SIZE_THRESHOLD = 2048;
+
+/**
+ * Select the lowest-cost healthy model from candidates (SP-085).
+ */
+export function selectLowestCostModel(
+  candidates: readonly ModelProfile[],
+): ModelProfile | undefined {
+  let best: ModelProfile | undefined;
+  let bestCost = Infinity;
+
+  for (const model of candidates) {
+    if (model.healthy === false) continue;
+    const cost = model.pricing.fallback_cost_per_1m;
+    if (cost < bestCost) {
+      bestCost = cost;
+      best = model;
+    }
+  }
+
+  return best;
+}
+
+// ─── Policy ───────────────────────────────────────────────────────────────────
+
+/**
+ * Evaluate sub-route eligibility for a single request against a session pin.
+ *
+ * Designed for the hot path — no allocation beyond the return object,
+ * no I/O, deterministic.
+ */
+export function evaluateSubRoutePolicy(
+  request: RoutingRequest,
+  pin: SessionPin,
+  fleet: readonly ModelProfile[],
+  config?: SubRoutePolicyConfig,
+): SubRouteEvaluation {
+  const threshold = config?.sizeThreshold ?? DEFAULT_SIZE_THRESHOLD;
+
+  if (request.turn_type !== 'tool_result') {
+    return { eligible: false, reason: 'not_tool_result' };
+  }
+
+  const payloadSize =
+    request.estimated_input_tokens ?? request.prompt_text.length;
+
+  if (payloadSize > threshold) {
+    return { eligible: false, reason: 'payload_exceeds_threshold' };
+  }
+
+  const pinnedModel = fleet.find((m) => m.id === pin.pinned_model_id);
+  if (!pinnedModel) {
+    return { eligible: false, reason: 'pinned_model_not_in_fleet' };
+  }
+
+  const candidates = fleet.filter(
+    (m) =>
+      m.tier === 'economical-cloud' &&
+      m.provider === pinnedModel.provider &&
+      m.id !== pin.pinned_model_id &&
+      m.healthy !== false,
+  );
+
+  const econModel = selectLowestCostModel(candidates);
+
+  if (!econModel) {
+    return { eligible: false, reason: 'no_same_provider_economical' };
+  }
+
+  return {
+    eligible: true,
+    subRouteModel: econModel,
+    pinnedModel,
+    reason: 'eligible',
+  };
+}