pi-smart-router 0.1.0

package/src/config/pi-model-mapper.ts

@@ -0,0 +1,285 @@
+/**
+ * Pi model registry → ModelProfile mapper.
+ *
+ * Maps pi `Model` objects (provider + id) to router fleet entries using
+ * pattern-based lookup for known families. Unknown models receive conservative
+ * economical-cloud defaults.
+ */
+
+import type {
+  ModelCapabilities,
+  ModelLimits,
+  ModelPerformance,
+  ModelPricing,
+  ModelProfile,
+  Tier,
+} from '../domain/types/entities.js';
+
+/** Pi registry `Model.cost` shape — per-token USD rates. */
+export interface PiRegistryCost {
+  readonly input: number;
+  readonly output: number;
+  readonly cacheRead: number;
+  readonly cacheWrite: number;
+}
+
+export interface PiModelInput {
+  readonly provider: string;
+  readonly id: string;
+  readonly name?: string;
+  readonly cost?: PiRegistryCost;
+}
+
+interface ModelFamilyDefaults {
+  readonly tier: Tier;
+  readonly capabilities: ModelCapabilities;
+  readonly performance?: ModelPerformance;
+  readonly pricing: ModelPricing;
+  readonly endpoint?: string;
+}
+
+interface ModelPatternRule {
+  readonly pattern: RegExp;
+  readonly defaults: ModelFamilyDefaults;
+}
+
+const LOCAL_PROVIDERS = new Set(['lmstudio', 'ollama']);
+
+/** Conservative context limits when YAML and LiteLLM registry have no entry (SP-092). */
+export const DEFAULT_MODEL_LIMITS: Readonly<Record<Tier, ModelLimits>> = {
+  'zero-tier': { max_input_tokens: 32_768, max_output_tokens: 4_096 },
+  'economical-cloud': { max_input_tokens: 128_000, max_output_tokens: 8_192 },
+  'frontier-cloud': { max_input_tokens: 200_000, max_output_tokens: 16_384 },
+};
+
+export function getDefaultLimitsForTier(tier: Tier): ModelLimits {
+  return { ...DEFAULT_MODEL_LIMITS[tier] };
+}
+
+const LOCAL_DEFAULTS: ModelFamilyDefaults = {
+  tier: 'zero-tier',
+  capabilities: { reasoning: 0.3, code_gen: 0.6, tool_use: 0.1 },
+  performance: {
+    latency_p50_ms: 120,
+    verbosity_factor: 0.9,
+    cache_friendly: true,
+  },
+  pricing: {
+    registry_key: 'local/free',
+    fallback_cost_per_1m: 0.0,
+  },
+  endpoint: 'http://localhost:1234/v1',
+};
+
+const FRONTIER_DEFAULTS: ModelFamilyDefaults = {
+  tier: 'frontier-cloud',
+  capabilities: { reasoning: 0.95, code_gen: 0.95, tool_use: 0.95 },
+  performance: {
+    latency_p50_ms: 450,
+    verbosity_factor: 1.2,
+    cache_friendly: true,
+  },
+  pricing: {
+    fallback_cost_per_1m: 3.0,
+  },
+};
+
+const ECONOMICAL_DEFAULTS: ModelFamilyDefaults = {
+  tier: 'economical-cloud',
+  capabilities: { reasoning: 0.7, code_gen: 0.75, tool_use: 0.7 },
+  performance: {
+    latency_p50_ms: 280,
+    verbosity_factor: 0.95,
+    cache_friendly: true,
+  },
+  pricing: {
+    fallback_cost_per_1m: 0.8,
+  },
+};
+
+const UNKNOWN_DEFAULTS: ModelFamilyDefaults = {
+  tier: 'economical-cloud',
+  capabilities: { reasoning: 0.6, code_gen: 0.65, tool_use: 0.6 },
+  performance: {
+    latency_p50_ms: 350,
+    verbosity_factor: 1.0,
+    cache_friendly: true,
+  },
+  pricing: {
+    fallback_cost_per_1m: 1.0,
+  },
+};
+
+/**
+ * Default virtual subscription-quota cost for Cursor frontier models (SP-096 / #70).
+ * `fallback_cost_per_1m` stays 0 (no per-token API billing); `quota_cost_per_1m`
+ * is used only for frugality scoring and telemetry so economical API models are
+ * not dominated solely because subscription registry cost is zero.
+ */
+export const DEFAULT_CURSOR_QUOTA_COST_PER_1M = 3.0;
+
+/**
+ * Opaque pi/Cursor fleet placeholder id `default` — SP-098 / #70.
+ * Without an explicit rule this id fell through to UNKNOWN_DEFAULTS (economical-cloud)
+ * and won turn_envelope lowest-cost selection for tool_result turns.
+ */
+const OPAQUE_FLEET_DEFAULT_ID = 'default';
+
+/**
+ * Cursor opaque-auto models (`cursor/auto`, etc.) — SP-086 / #40.
+ * Frontier tier: Cursor picks the underlying model; HyDRA needs high capability
+ * scores so these are not dominated by mapped economical Gemini/OpenAI models.
+ * Registry `fallback_cost_per_1m` is zero (subscription billing); virtual quota
+ * cost (SP-096) drives frugality scoring and telemetry.
+ */
+const CURSOR_AUTO_DEFAULTS: ModelFamilyDefaults = {
+  tier: 'frontier-cloud',
+  capabilities: { reasoning: 0.9, code_gen: 0.9, tool_use: 0.95 },
+  performance: {
+    latency_p50_ms: 350,
+    verbosity_factor: 1.0,
+    cache_friendly: false,
+  },
+  pricing: {
+    fallback_cost_per_1m: 0.0,
+    quota_cost_per_1m: DEFAULT_CURSOR_QUOTA_COST_PER_1M,
+  },
+};
+
+/**
+ * Cursor Composer coding models (`composer-latest`, `composer-*`) — SP-086 / #40.
+ * Frontier tier with strong code_gen; zero API fallback with virtual quota cost (SP-096).
+ */
+const COMPOSER_DEFAULTS: ModelFamilyDefaults = {
+  tier: 'frontier-cloud',
+  capabilities: { reasoning: 0.85, code_gen: 0.95, tool_use: 0.9 },
+  performance: {
+    latency_p50_ms: 400,
+    verbosity_factor: 1.05,
+    cache_friendly: false,
+  },
+  pricing: {
+    fallback_cost_per_1m: 0.0,
+    quota_cost_per_1m: DEFAULT_CURSOR_QUOTA_COST_PER_1M,
+  },
+};
+
+/** Ordered rules — first match wins. */
+const MODEL_PATTERN_RULES: readonly ModelPatternRule[] = [
+  { pattern: /claude[-_.]?opus|claude[-_.]?sonnet|opus|sonnet/i, defaults: FRONTIER_DEFAULTS },
+  { pattern: /claude[-_.]?haiku|haiku/i, defaults: ECONOMICAL_DEFAULTS },
+  { pattern: /gpt[-_.]?5\.5|gpt-5-5/i, defaults: FRONTIER_DEFAULTS },
+  { pattern: /gpt[-_.]?5\.1|gpt[-_.]?5[-_.]?mini|gpt[-_.]?mini/i, defaults: ECONOMICAL_DEFAULTS },
+  { pattern: /gemini[-_.]?2\.5[-_.]?pro|gemini-2-5-pro/i, defaults: FRONTIER_DEFAULTS },
+  { pattern: /gemini[-_.]?3.*pro/i, defaults: FRONTIER_DEFAULTS },
+  { pattern: /gemini.*pro/i, defaults: FRONTIER_DEFAULTS },
+  { pattern: /gemini.*flash|gemini-flash/i, defaults: ECONOMICAL_DEFAULTS },
+  { pattern: /^composer[-_]/i, defaults: COMPOSER_DEFAULTS },
+  { pattern: /^cursor\//i, defaults: CURSOR_AUTO_DEFAULTS },
+];
+
+function normalizeProvider(provider: string): string {
+  return provider.trim().toLowerCase();
+}
+
+function matchPatternRules(id: string): ModelFamilyDefaults | undefined {
+  for (const rule of MODEL_PATTERN_RULES) {
+    if (rule.pattern.test(id)) {
+      return rule.defaults;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Registry cost → USD per 1M tokens: average of input and output rates scaled to 1M.
+ * Matches `computeCostPer1MTokens` in litellm-fetch (SP-045/SP-046).
+ * Returns undefined when both input and output rates are zero (use pattern default).
+ */
+function deriveFallbackCostPer1M(cost: PiRegistryCost): number | undefined {
+  const { input, output } = cost;
+  if (input === 0 && output === 0) {
+    return undefined;
+  }
+
+  const inputPer1M = input * 1_000_000;
+  const outputPer1M = output * 1_000_000;
+  return (inputPer1M + outputPer1M) / 2;
+}
+
+function resolveFallbackCost(
+  input: PiModelInput,
+  defaults: ModelFamilyDefaults,
+): number {
+  if (input.cost === undefined) {
+    return defaults.pricing.fallback_cost_per_1m;
+  }
+
+  const fromRegistry = deriveFallbackCostPer1M(input.cost);
+  return fromRegistry ?? defaults.pricing.fallback_cost_per_1m;
+}
+
+function buildProfile(input: PiModelInput, defaults: ModelFamilyDefaults): ModelProfile {
+  const provider = input.provider.trim();
+  const registryKey = `${normalizeProvider(provider)}/${input.id}`;
+
+  const profile: ModelProfile = {
+    id: input.id,
+    tier: defaults.tier,
+    provider,
+    capabilities: { ...defaults.capabilities },
+    pricing: {
+      registry_key: defaults.pricing.registry_key ?? registryKey,
+      fallback_cost_per_1m: resolveFallbackCost(input, defaults),
+      ...(defaults.pricing.quota_cost_per_1m !== undefined
+        ? { quota_cost_per_1m: defaults.pricing.quota_cost_per_1m }
+        : {}),
+    },
+  };
+
+  const withPerformance =
+    defaults.performance !== undefined
+      ? { ...profile, performance: { ...defaults.performance } }
+      : profile;
+
+  if (defaults.endpoint !== undefined) {
+    return { ...withPerformance, endpoint: defaults.endpoint };
+  }
+
+  return withPerformance;
+}
+
+/**
+ * Map a pi model registry entry to a router ModelProfile.
+ */
+export function mapPiModelToProfile(input: PiModelInput): ModelProfile {
+  const provider = normalizeProvider(input.provider);
+
+  if (LOCAL_PROVIDERS.has(provider)) {
+    // Local models stay free — registry cost must not override zero-tier pricing.
+    const localInput: PiModelInput = {
+      provider: input.provider,
+      id: input.id,
+      ...(input.name !== undefined ? { name: input.name } : {}),
+    };
+    return buildProfile(localInput, LOCAL_DEFAULTS);
+  }
+
+  if (input.id === OPAQUE_FLEET_DEFAULT_ID) {
+    return buildProfile(input, CURSOR_AUTO_DEFAULTS);
+  }
+
+  const matched = matchPatternRules(input.id);
+  if (matched) {
+    return buildProfile(input, matched);
+  }
+
+  return buildProfile(input, UNKNOWN_DEFAULTS);
+}
+
+/**
+ * Map an array of pi registry models to a router fleet catalog.
+ */
+export function mapFleetFromRegistry(models: readonly PiModelInput[]): ModelProfile[] {
+  return models.map(mapPiModelToProfile);
+}

package/src/config/routing-clusters-loader.ts

@@ -0,0 +1,148 @@
+/**
+ * Routing cluster catalog loader — reads routing-clusters.yaml, validates via Zod,
+ * and precomputes centroid embeddings from reference prompts at load time.
+ *
+ * Maps to GitHub issue #55 / SP-099.
+ */
+
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+import { RoutingClustersFileSchema } from '../domain/types/schemas.js';
+import type {
+  LoadedRoutingCluster,
+  RoutingCluster,
+  RoutingClusterCatalog,
+} from '../domain/types/index.js';
+
+/** Prefix for cluster match reason codes (`cluster_low_stakes_general`, etc.). */
+export const CLUSTER_REASON_CODE_PREFIX = 'cluster_';
+
+export interface TextEmbedder {
+  embed(text: string): Promise<Float32Array>;
+}
+
+export interface LoadRoutingClustersOptions {
+  readonly filePath?: string;
+  readonly embedder: TextEmbedder;
+}
+
+export class RoutingClustersLoaderError extends Error {
+  override readonly name = 'RoutingClustersLoaderError';
+
+  constructor(message: string, options?: ErrorOptions) {
+    super(message, options);
+  }
+}
+
+/** Stable reason-code prefix for a cluster id. */
+export function clusterReasonCode(clusterId: string): string {
+  return `${CLUSTER_REASON_CODE_PREFIX}${clusterId}`;
+}
+
+function formatZodIssues(error: { issues: readonly { path: readonly PropertyKey[]; message: string }[] }): string {
+  return error.issues
+    .map((issue) => `  - ${issue.path.join('.')}: ${issue.message}`)
+    .join('\n');
+}
+
+/**
+ * Parse and validate routing cluster YAML without computing centroids.
+ *
+ * @throws {RoutingClustersLoaderError} when validation fails.
+ */
+export function parseRoutingClustersYaml(raw: string): readonly RoutingCluster[] {
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(raw);
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new RoutingClustersLoaderError(`Failed to parse YAML: ${message}`, { cause: err });
+  }
+
+  const result = RoutingClustersFileSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new RoutingClustersLoaderError(
+      `Invalid routing cluster catalog:\n${formatZodIssues(result.error)}`,
+      { cause: result.error },
+    );
+  }
+
+  return result.data.clusters;
+}
+
+function computeCentroid(embeddings: readonly Float32Array[]): Float32Array {
+  if (embeddings.length === 0) {
+    throw new RoutingClustersLoaderError('Cannot compute centroid from zero embeddings');
+  }
+
+  const dim = embeddings[0]!.length;
+  const centroid = new Float32Array(dim);
+
+  for (const embedding of embeddings) {
+    if (embedding.length !== dim) {
+      throw new RoutingClustersLoaderError(
+        `Embedding shape mismatch: expected ${dim}, got ${embedding.length}`,
+      );
+    }
+    for (let i = 0; i < dim; i++) {
+      centroid[i] = (centroid[i] ?? 0) + (embedding[i] ?? 0);
+    }
+  }
+
+  for (let i = 0; i < dim; i++) {
+    centroid[i] = (centroid[i] ?? 0) / embeddings.length;
+  }
+
+  return centroid;
+}
+
+async function loadClusterCentroids(
+  clusters: readonly RoutingCluster[],
+  embedder: TextEmbedder,
+): Promise<readonly LoadedRoutingCluster[]> {
+  const loaded: LoadedRoutingCluster[] = [];
+
+  for (const cluster of clusters) {
+    const embeddings: Float32Array[] = [];
+    for (const prompt of cluster.reference_prompts) {
+      embeddings.push(await embedder.embed(prompt));
+    }
+
+    loaded.push({
+      ...cluster,
+      centroid: computeCentroid(embeddings),
+    });
+  }
+
+  return loaded;
+}
+
+/**
+ * Load, validate, and precompute centroid embeddings for the routing cluster catalog.
+ *
+ * @throws {RoutingClustersLoaderError} when the file cannot be read or validation fails.
+ */
+export async function loadRoutingClusters(
+  options: LoadRoutingClustersOptions,
+): Promise<RoutingClusterCatalog> {
+  const filePath = options.filePath ?? resolve('config', 'routing-clusters.yaml');
+
+  let raw: string;
+  try {
+    raw = readFileSync(filePath, 'utf8');
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new RoutingClustersLoaderError(
+      `Failed to read routing clusters file: ${message}`,
+      { cause: err },
+    );
+  }
+
+  const clusters = parseRoutingClustersYaml(raw);
+  const loaded = await loadClusterCentroids(clusters, options.embedder);
+
+  return { clusters: loaded };
+}

package/src/domain/delegation/delegation-context.ts

@@ -0,0 +1,111 @@
+/**
+ * Delegation context normalization — provider-agnostic replay identity fix.
+ *
+ * pi-ai transformMessages compares assistant message provider/api/model to the
+ * target model. Virtual smart-router tags break isSameModel and strip replay
+ * state (thoughtSignature, thinkingSignature, etc.).
+ */
+
+import type {
+  Api,
+  AssistantMessage,
+  Context,
+  Message,
+  Model,
+} from '@earendil-works/pi-ai/compat';
+
+import type { ExecutionModel } from './execution-ledger.js';
+
+export const VIRTUAL_ROUTER_PROVIDER = 'smart-router' as const;
+export const VIRTUAL_ROUTER_MODEL_ID = 'auto' as const;
+
+export function isVirtualRouterIdentity(provider: string, modelId: string): boolean {
+  return provider === VIRTUAL_ROUTER_PROVIDER && modelId === VIRTUAL_ROUTER_MODEL_ID;
+}
+
+export function hasReplaySensitiveState(messages: readonly Message[]): boolean {
+  for (const message of messages) {
+    if (message.role !== 'assistant') {
+      continue;
+    }
+
+    for (const block of message.content) {
+      if (block.type === 'thinking') {
+        if (block.redacted) {
+          return true;
+        }
+        if (block.thinkingSignature && block.thinkingSignature.length > 0) {
+          return true;
+        }
+      }
+
+      if (block.type === 'text' && block.textSignature && block.textSignature.length > 0) {
+        return true;
+      }
+
+      if (
+        block.type === 'toolCall' &&
+        block.thoughtSignature &&
+        block.thoughtSignature.length > 0
+      ) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function rewriteAssistantIdentity(
+  message: AssistantMessage,
+  executionModel: ExecutionModel,
+): AssistantMessage {
+  return {
+    ...message,
+    provider: executionModel.provider as AssistantMessage['provider'],
+    api: executionModel.api,
+    model: executionModel.id,
+  };
+}
+
+export interface NormalizeDelegationContextOptions {
+  readonly virtualProvider?: typeof VIRTUAL_ROUTER_PROVIDER;
+  readonly sessionExecution?: ExecutionModel | null;
+}
+
+/**
+ * Rewrite assistant messages tagged with the virtual router to the executing
+ * model identity pi-ai expects for same-model replay.
+ */
+export function normalizeDelegationContext<TApi extends Api>(
+  context: Context,
+  targetModel: Model<TApi>,
+  options?: NormalizeDelegationContextOptions,
+): Context {
+  const virtualProvider = options?.virtualProvider ?? VIRTUAL_ROUTER_PROVIDER;
+  const fallbackExecution: ExecutionModel = {
+    provider: targetModel.provider,
+    api: targetModel.api,
+    id: targetModel.id,
+  };
+  const sessionExecution = options?.sessionExecution ?? null;
+  const executionForVirtual = sessionExecution ?? fallbackExecution;
+
+  const messages = context.messages.map((message) => {
+    if (message.role !== 'assistant') {
+      return message;
+    }
+
+    const assistant = message;
+    if (
+      assistant.provider === virtualProvider &&
+      assistant.model === VIRTUAL_ROUTER_MODEL_ID
+    ) {
+      return rewriteAssistantIdentity(assistant, executionForVirtual);
+    }
+
+    return message;
+  });
+
+  return { ...context, messages };
+}

package/src/domain/delegation/execution-ledger.ts

@@ -0,0 +1,34 @@
+/**
+ * Tracks the last successfully executing model per session.
+ *
+ * Used to rewrite virtual smart-router assistant identity on replay so pi-ai
+ * transformMessages sees the model that actually produced prior turns.
+ */
+
+import type { Api } from '@earendil-works/pi-ai/compat';
+
+export interface ExecutionModel {
+  readonly provider: string;
+  readonly api: Api;
+  readonly id: string;
+}
+
+export class ExecutionLedger {
+  private readonly bySession = new Map<string, ExecutionModel>();
+
+  recordSuccess(sessionId: string, model: ExecutionModel): void {
+    this.bySession.set(sessionId, {
+      provider: model.provider,
+      api: model.api,
+      id: model.id,
+    });
+  }
+
+  getLastExecution(sessionId: string): ExecutionModel | null {
+    return this.bySession.get(sessionId) ?? null;
+  }
+
+  clear(sessionId: string): void {
+    this.bySession.delete(sessionId);
+  }
+}

package/src/domain/delegation/output-headroom.ts

@@ -0,0 +1,131 @@
+/**
+ * Delegation output headroom — SP-108.
+ *
+ * Reserves output budget from the model context window before provider dispatch.
+ * Prevents stopReason "length" with zero output when input consumes the window.
+ */
+
+import type { Api, Model } from '@earendil-works/pi-ai/compat';
+
+import type { ModelProfile } from '../types/index.js';
+
+export const MIN_OUTPUT_TOKEN_FLOOR = 256;
+export const DEFAULT_OUTPUT_HEADROOM_BUFFER = 64;
+
+export const MIN_OUTPUT_TOKEN_FLOOR_ENV = 'MIN_OUTPUT_TOKEN_FLOOR';
+export const OUTPUT_HEADROOM_BUFFER_ENV = 'OUTPUT_HEADROOM_BUFFER';
+
+export interface OutputHeadroomConfig {
+  readonly minOutputFloor?: number;
+  readonly buffer?: number;
+}
+
+export interface OutputHeadroomFit {
+  readonly kind: 'fit';
+  readonly maxTokens: number;
+  readonly contextWindow: number;
+}
+
+export interface OutputHeadroomNoFit {
+  readonly kind: 'no_fit';
+  readonly contextWindow: number;
+  readonly availableOutputTokens: number;
+}
+
+export type OutputHeadroomResult = OutputHeadroomFit | OutputHeadroomNoFit;
+
+function readPositiveIntEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === '') {
+    return fallback;
+  }
+
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+
+  return Math.floor(parsed);
+}
+
+export function resolveMinOutputFloor(config?: OutputHeadroomConfig): number {
+  if (config?.minOutputFloor !== undefined) {
+    return config.minOutputFloor;
+  }
+  return readPositiveIntEnv(MIN_OUTPUT_TOKEN_FLOOR_ENV, MIN_OUTPUT_TOKEN_FLOOR);
+}
+
+export function resolveOutputHeadroomBuffer(config?: OutputHeadroomConfig): number {
+  if (config?.buffer !== undefined) {
+    return config.buffer;
+  }
+  return readPositiveIntEnv(OUTPUT_HEADROOM_BUFFER_ENV, DEFAULT_OUTPUT_HEADROOM_BUFFER);
+}
+
+export function resolveContextWindow(
+  profile: ModelProfile,
+  registryModel?: Model<Api>,
+): number {
+  return (
+    profile.limits?.max_input_tokens ??
+    registryModel?.contextWindow ??
+    Number.MAX_SAFE_INTEGER
+  );
+}
+
+export function resolveMaxOutputCap(
+  profile: ModelProfile,
+  registryModel?: Model<Api>,
+): number {
+  return (
+    profile.limits?.max_output_tokens ??
+    registryModel?.maxTokens ??
+    Number.MAX_SAFE_INTEGER
+  );
+}
+
+/**
+ * Compute delegatable maxTokens and whether output headroom meets the floor.
+ *
+ * Validates `estimatedInputTokens + minOutputFloor <= contextWindow` and returns
+ * `maxTokens = min(maxOutputCap, contextWindow - estimatedInput - buffer)`.
+ */
+export function computeOutputHeadroom(
+  profile: ModelProfile,
+  estimatedInputTokens: number,
+  config?: OutputHeadroomConfig,
+  registryModel?: Model<Api>,
+): OutputHeadroomResult {
+  const contextWindow = resolveContextWindow(profile, registryModel);
+  const minFloor = resolveMinOutputFloor(config);
+  const buffer = resolveOutputHeadroomBuffer(config);
+  const maxOutputCap = resolveMaxOutputCap(profile, registryModel);
+
+  if (contextWindow === Number.MAX_SAFE_INTEGER) {
+    const maxTokens = Math.min(maxOutputCap, Number.MAX_SAFE_INTEGER);
+    return { kind: 'fit', maxTokens, contextWindow };
+  }
+
+  const availableOutputTokens = contextWindow - estimatedInputTokens;
+
+  if (estimatedInputTokens + minFloor > contextWindow) {
+    return {
+      kind: 'no_fit',
+      contextWindow,
+      availableOutputTokens: Math.max(0, availableOutputTokens),
+    };
+  }
+
+  const rawMaxTokens = contextWindow - estimatedInputTokens - buffer;
+  const maxTokens = Math.min(maxOutputCap, rawMaxTokens);
+
+  if (maxTokens < minFloor) {
+    return {
+      kind: 'no_fit',
+      contextWindow,
+      availableOutputTokens: rawMaxTokens,
+    };
+  }
+
+  return { kind: 'fit', maxTokens, contextWindow };
+}