@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/model-router.mjs

@@ -3,38 +3,39 @@
  *
  * What it does:
  *   • Defines provider-family tier mappings and resolves model IDs.
- *   • Polls OpenRouter for free models, scores them, and selects appropriate
- *     alternatives for each tier (reasoning, standard, fast).
- *   • Provides helpers to apply free-preference modes (global, same‑family,
+ *   • Provides helpers to apply free-preference modes (global, same-family,
  *     explicit selection) and to persist selections to .env.
+ *   • Provider-aware failover: classifies failures, resolves fallback candidates,
+ *     and tracks per-provider cooldowns in ~/.cx/provider-cooldowns.json.
  *
  * Consumed by:
- *   • lib/cli-commands.mjs   – model configuration commands.
- *   • lib/model-router.mjs   – internal model inference utilities.
- *   • lib/setup.mjs          – environment variable generation.
+ *   • bin/construct                  – model configuration commands.
+ *   • lib/prompt-composer.js        – execution contract metadata.
+ *   • lib/mcp/server.mjs             – runtime model resolution.
+ *   • lib/setup.mjs                  – environment variable generation.
+ *   • lib/hooks/model-fallback.mjs   – automatic failover on rate-limit / outage.
  *
  * Maintenance:
- *   • Adding new provider families → extend `PROVIDER_FAMILY_TIERS` with a
- *     `test`/`resolve` entry.
- *   • Changing scoring logic → modify `_score()` function.
- *   • Adjusting token‑budget behavior → edit `applyFreeSameFamilyPreferenceToTierSet()`.
- *   • Persisting selections → update `applyToEnv()` comment block.
+ *   • Adding new provider families → extend `PROVIDER_FAMILY_TIERS`.
+ *   • Changing scoring logic → modify `score()` in model-free-selector.mjs.
+ *   • Persisting selections → update `applyToEnv()`.
+ *   • Cooldown window → change `PROVIDER_COOLDOWN_MS`.
  */
 import fs from "node:fs";
 import path from "node:path";
+import { spawnSync } from "child_process";
 import { findOpenCodeConfigPath } from "./opencode-config.mjs";
-
-const OPENROUTER_MODELS_URL = "https://openrouter.ai/api/v1/models";
-const FETCH_TIMEOUT_MS = 10_000;
-
-/**
- * Built‑in default model IDs for each tier when no overrides are present.
- */
-const BUILTIN_DEFAULTS = {
-  reasoning: "openrouter/deepseek/deepseek-r1",
-  standard: "openrouter/qwen/qwen3-coder:free",
-  fast: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
-};
+import {
+  isFreeModel,
+  pollFreeModels,
+  preferFreeValue,
+  selectForTier,
+  topForTier,
+} from "./model-free-selector.mjs";
+
+function uniqueStrings(values = []) {
+  return [...new Set(values.filter((value) => typeof value === "string" && value.trim()))];
+}
 
 export const MODEL_TIER_BY_WORK_CATEGORY = {
   visual: "standard",
@@ -45,7 +46,7 @@ export const MODEL_TIER_BY_WORK_CATEGORY = {
 };
 
 /**
- * Provider‑family definitions. Each entry contains:
+ * Provider-family definitions. Each entry contains:
  *   - `test`: RegExp that matches provider URLs.
  *   - `resolve`: Function that maps selected tier values to concrete model IDs.
  *
@@ -53,54 +54,98 @@ export const MODEL_TIER_BY_WORK_CATEGORY = {
  */
 const PROVIDER_FAMILY_TIERS = [
   {
+    id: 'anthropic',
+    label: 'Anthropic (direct)',
     test: (modelId) => /^anthropic\//.test(modelId),
     resolve: ({ reasoning, standard, fast }) => ({
       reasoning: reasoning ?? "anthropic/claude-opus-4-6",
       standard: standard ?? "anthropic/claude-sonnet-4-6",
       fast: fast ?? "anthropic/claude-haiku-4-5-20251001",
     }),
+    options: {
+      reasoning: ["anthropic/claude-opus-4-6", "anthropic/claude-sonnet-4-6"],
+      standard: ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-6"],
+      fast: ["anthropic/claude-haiku-4-5-20251001", "anthropic/claude-sonnet-4-6"],
+    },
   },
   {
+    id: 'openrouter-anthropic',
+    label: 'Anthropic via OpenRouter',
     test: (modelId) => /^openrouter\/anthropic\//.test(modelId),
     resolve: ({ reasoning, standard, fast }) => ({
       reasoning: reasoning ?? "openrouter/anthropic/claude-opus-4-6",
       standard: standard ?? "openrouter/anthropic/claude-sonnet-4-6",
       fast: fast ?? "openrouter/anthropic/claude-haiku-4-5-20251001",
     }),
+    options: {
+      reasoning: ["openrouter/anthropic/claude-opus-4-6", "openrouter/anthropic/claude-sonnet-4-6"],
+      standard: ["openrouter/anthropic/claude-sonnet-4-6", "openrouter/anthropic/claude-opus-4-6"],
+      fast: ["openrouter/anthropic/claude-haiku-4-5-20251001", "openrouter/anthropic/claude-sonnet-4-6"],
+    },
   },
   {
+    id: 'openrouter-google',
+    label: 'Google via OpenRouter',
     test: (modelId) => /^openrouter\/google\//.test(modelId),
     resolve: ({ reasoning, standard, fast }) => ({
       reasoning: reasoning ?? "openrouter/google/gemini-2.5-pro",
       standard: standard ?? "openrouter/google/gemini-2.0-flash-001",
       fast: fast ?? "openrouter/google/gemma-3-27b-it:free",
     }),
+    options: {
+      reasoning: ["openrouter/google/gemini-2.5-pro", "openrouter/google/gemini-2.5-flash"],
+      standard: ["openrouter/google/gemini-2.0-flash-001", "openrouter/google/gemini-2.5-flash"],
+      fast: ["openrouter/google/gemma-3-27b-it:free", "openrouter/google/gemini-2.0-flash-001"],
+    },
   },
   {
+    id: 'openrouter-deepseek',
+    label: 'DeepSeek via OpenRouter',
     test: (modelId) => /^openrouter\/deepseek\//.test(modelId),
     resolve: ({ reasoning, standard, fast }) => ({
       reasoning: reasoning ?? "openrouter/deepseek/deepseek-r1",
       standard: standard ?? "openrouter/deepseek/deepseek-v3",
       fast: fast ?? standard ?? "openrouter/qwen/qwen3-coder:free",
     }),
+    options: {
+      reasoning: ["openrouter/deepseek/deepseek-r1", "openrouter/deepseek/deepseek-v3"],
+      standard: ["openrouter/deepseek/deepseek-v3", "openrouter/deepseek/deepseek-r1"],
+      fast: ["openrouter/qwen/qwen3-coder:free", "openrouter/deepseek/deepseek-v3"],
+    },
   },
   {
+    id: 'openrouter-qwen',
+    label: 'Qwen via OpenRouter',
     test: (modelId) => /^openrouter\/qwen\//.test(modelId),
     resolve: ({ reasoning, standard, fast }) => ({
       reasoning: reasoning ?? "openrouter/qwen/qwen3-coder",
       standard: standard ?? "openrouter/qwen/qwen3-coder:free",
       fast: fast ?? "openrouter/qwen/qwen2.5-coder-32b-instruct",
     }),
+    options: {
+      reasoning: ["openrouter/qwen/qwen3-coder", "openrouter/qwen/qwen3-coder:free"],
+      standard: ["openrouter/qwen/qwen3-coder:free", "openrouter/qwen/qwen3-coder"],
+      fast: ["openrouter/qwen/qwen2.5-coder-32b-instruct", "openrouter/qwen/qwen3-coder:free"],
+    },
   },
   {
+    id: 'github-copilot',
+    label: 'GitHub Copilot',
     test: (modelId) => /^github-copilot\//.test(modelId),
     resolve: ({ reasoning, standard, fast }) => ({
       reasoning: reasoning ?? "github-copilot/gpt-5.4",
       standard: standard ?? "github-copilot/gpt-5.1",
       fast: fast ?? "github-copilot/gpt-5.1-mini",
     }),
+    options: {
+      reasoning: ["github-copilot/gpt-5.4", "github-copilot/gpt-5.1"],
+      standard: ["github-copilot/gpt-5.1", "github-copilot/gpt-5.1-mini"],
+      fast: ["github-copilot/gpt-5.1-mini", "github-copilot/gpt-5.1"],
+    },
   },
   {
+    id: 'openai',
+    label: 'OpenAI',
     test: (modelId) => /^openai\//.test(modelId) || /^openrouter\/openai\//.test(modelId),
     resolve: ({ reasoning, standard, fast }) => {
       const prefix = /^openrouter\//.test(reasoning || standard || fast || "") ? "openrouter/openai" : "openai";
@@ -110,30 +155,207 @@ const PROVIDER_FAMILY_TIERS = [
         fast: fast ?? `${prefix}/gpt-5.1-mini`,
       };
     },
+    options: {
+      reasoning: ["openai/gpt-5.4", "openrouter/openai/gpt-5.4", "openai/gpt-5.1"],
+      standard: ["openai/gpt-5.1", "openrouter/openai/gpt-5.1", "openai/gpt-5.1-mini"],
+      fast: ["openai/gpt-5.1-mini", "openrouter/openai/gpt-5.1-mini", "openai/gpt-5.1"],
+    },
   },
   {
+    id: 'openrouter-llama',
+    label: 'Meta Llama via OpenRouter',
     test: (modelId) => /^openrouter\/meta-llama\//.test(modelId),
     resolve: ({ reasoning, standard, fast }) => ({
       reasoning: reasoning ?? "openrouter/meta-llama/llama-3.1-405b-instruct",
       standard: standard ?? "openrouter/meta-llama/llama-3.3-70b-instruct",
       fast: fast ?? "openrouter/meta-llama/llama-3.3-70b-instruct:free",
     }),
+    options: {
+      reasoning: ["openrouter/meta-llama/llama-3.1-405b-instruct", "openrouter/meta-llama/llama-3.3-70b-instruct"],
+      standard: ["openrouter/meta-llama/llama-3.3-70b-instruct", "openrouter/meta-llama/llama-3.3-70b-instruct:free"],
+      fast: ["openrouter/meta-llama/llama-3.3-70b-instruct:free", "openrouter/meta-llama/llama-3.3-70b-instruct"],
+    },
+  },
+  {
+    id: 'ollama',
+    label: 'Ollama (local)',
+    test: (modelId) => /^ollama\//.test(modelId),
+    resolve: ({ reasoning, standard, fast }) => ({
+      reasoning: reasoning ?? "ollama/llama3.1:70b",
+      standard: standard ?? "ollama/llama3.1:8b",
+      fast: fast ?? "ollama/llama3.2:3b",
+    }),
+    options: {
+      reasoning: ["ollama/llama3.1:70b", "ollama/qwen2.5:32b", "ollama/deepseek-r1:32b"],
+      standard: ["ollama/llama3.1:8b", "ollama/qwen2.5:7b", "ollama/mistral:7b"],
+      fast: ["ollama/llama3.2:3b", "ollama/phi3:mini", "ollama/qwen2.5:3b"],
+    },
+    local: true,
+    requiresEnv: ['OLLAMA_BASE_URL'],
+    pricingHint: 'free · runs locally',
+  },
+  {
+    id: 'local',
+    label: 'Local OpenAI-compatible server',
+    test: (modelId) => /^local\//.test(modelId),
+    resolve: ({ reasoning, standard, fast }) => ({
+      reasoning: reasoning ?? "local/custom-large",
+      standard: standard ?? "local/custom-medium",
+      fast: fast ?? "local/custom-small",
+    }),
+    options: {
+      reasoning: ["local/custom-large"],
+      standard: ["local/custom-medium"],
+      fast: ["local/custom-small"],
+    },
+    local: true,
+    requiresEnv: ['LOCAL_LLM_BASE_URL'],
+    pricingHint: 'free · runs locally',
   },
 ];
 
+export { PROVIDER_FAMILY_TIERS };
+
+/**
+ * Map provider family IDs to the env var(s) that indicate the provider
+ * is configured (has credentials). Used by getProviderModelCatalog to
+ * mark which providers are available.
+ */
+const PROVIDER_ENV_MAP = {
+  'anthropic': ['ANTHROPIC_API_KEY'],
+  'openrouter-anthropic': ['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'],
+  'openrouter-google': ['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'],
+  'openrouter-deepseek': ['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'],
+  'openrouter-qwen': ['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'],
+  'github-copilot': ['GITHUB_TOKEN', 'GH_TOKEN'],
+  'openai': ['OPENAI_API_KEY'],
+  'openrouter-llama': ['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'],
+  'ollama': ['OLLAMA_BASE_URL'],
+  'local': ['LOCAL_LLM_BASE_URL'],
+};
+
 /**
- * Find the provider‑family entry that matches a given model identifier.
- * @param {string} modelId – The model ID string.
- * @returns {object|null} – The matching tier‑resolution object, or `null`.
+ * Check if a provider is configured by checking env vars and CLI tools.
+ * Uses the passed env, then checks config.env, then checks gh CLI for Copilot.
+ */
+function isProviderConfigured(familyId, env) {
+  const varNames = PROVIDER_ENV_MAP[familyId];
+  if (!varNames?.length) return false;
+
+  // Special case: Ollama on default port (no OLLAMA_BASE_URL needed)
+  if (familyId === 'ollama') {
+    try {
+      const r = spawnSync('curl', ['-s', '--connect-timeout', '1', '-o', '/dev/null', '-w', '%{http_code}', 'http://localhost:11434/api/tags'], { encoding: 'utf8', timeout: 3000 });
+      if (r.status === 0 && r.stdout?.trim() === '200') return true;
+    } catch { /* not available */ }
+    try {
+      const r = spawnSync('ollama', ['--version'], { encoding: 'utf8', timeout: 2000 });
+      if (r.status === 0) return true;
+    } catch { /* not available */ }
+  }
+
+  // 1. Check passed env (usually process.env)
+  const anyInEnv = varNames.some(name => {
+    const val = env?.[name];
+    return val && typeof val === 'string' && val.length > 0;
+  });
+  if (anyInEnv) return true;
+
+  // 2. Check construct config.env
+  try {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '/tmp';
+    const cfgPath = path.join(homeDir, '.construct', 'config.env');
+    if (fs.existsSync(cfgPath)) {
+      const content = fs.readFileSync(cfgPath, 'utf8');
+      const anyInConfig = varNames.some(name => {
+        const re = new RegExp(`^${name}=["']?(.+?)["']?$`, 'm');
+        const m = content.match(re);
+        return m && m[1] && m[1].length > 0;
+      });
+      if (anyInConfig) return true;
+    }
+  } catch { /* skip */ }
+
+  // 3. Special case: GitHub Copilot via gh CLI
+  if (familyId === 'github-copilot') {
+    try {
+      const r = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', timeout: 3000 });
+      return r.status === 0;
+    } catch { return false; }
+  }
+
+  // 4. Check ~/.env
+  try {
+    const homeEnv = path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.env');
+    if (fs.existsSync(homeEnv)) {
+      const content = fs.readFileSync(homeEnv, 'utf8');
+      const anyInHomeEnv = varNames.some(name => {
+        const re = new RegExp(`^${name}=["']?(.+?)["']?$`, 'm');
+        const m = content.match(re);
+        return m && m[1] && m[1].length > 0;
+      });
+      if (anyInHomeEnv) return true;
+    }
+  } catch { /* skip */ }
+
+  // 5. Check shell rc files for op:// refs (1Password CLI integration)
+  try {
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '/tmp';
+    const shellFiles = ['.zshrc', '.bashrc', '.bash_profile', '.profile'].map(f => path.join(homeDir, f));
+    for (const rcPath of shellFiles) {
+      if (!fs.existsSync(rcPath)) continue;
+      const content = fs.readFileSync(rcPath, 'utf8');
+      const anyInRc = varNames.some(name => {
+        // Direct export (with or without command substitution)
+        const re = new RegExp(`^\\s*export\\s+${name}=`, 'm');
+        return re.test(content);
+      });
+      if (anyInRc) return true;
+    }
+  } catch { /* skip */ }
+
+  return false;
+}
+
+export function getProviderModelCatalog({ env = process.env } = {}) {
+  const providers = PROVIDER_FAMILY_TIERS.map((family) => {
+    const tiers = family.resolve({});
+    const options = {
+      reasoning: uniqueStrings([...(family.options?.reasoning ?? []), tiers.reasoning]),
+      standard: uniqueStrings([...(family.options?.standard ?? []), tiers.standard]),
+      fast: uniqueStrings([...(family.options?.fast ?? []), tiers.fast]),
+    };
+    return {
+      id: family.id,
+      label: family.label,
+      tiers,
+      options,
+      local: family.local === true,
+      requiresEnv: Array.isArray(family.requiresEnv) ? family.requiresEnv : [],
+      pricingHint: family.pricingHint ?? null,
+      configured: isProviderConfigured(family.id, env),
+    };
+  });
+
+  const tierOptions = {
+    reasoning: uniqueStrings(providers.flatMap((provider) => provider.options.reasoning)),
+    standard: uniqueStrings(providers.flatMap((provider) => provider.options.standard)),
+    fast: uniqueStrings(providers.flatMap((provider) => provider.options.fast)),
+  };
+
+  return { providers, tierOptions };
+}
+
+/**
+ * Find the provider-family entry that matches a given model identifier.
  */
 function matchProviderFamily(modelId) {
   return PROVIDER_FAMILY_TIERS.find((entry) => entry.test(modelId));
 }
 
 /**
- * Given a primary model the user selected, return tier → modelId mapping in
- * the same provider family. Returns null if no family matches (caller should
- * fall back to configured CX_MODEL_* values).
+ * Given a primary model the user selected, return tier -> modelId mapping in
+ * the same provider family. Returns null if no family matches.
  */
 export function resolveTiersForPrimary(primaryModelId) {
   if (!primaryModelId || typeof primaryModelId !== "string") return null;
@@ -143,11 +365,7 @@ export function resolveTiersForPrimary(primaryModelId) {
 }
 
 /**
- * Read the OpenRouter API key from the OpenCode config file instead of
- * requiring it to be exported as `OPENROUTER_API_KEY`.
- * @param {string} configPath – Path to the OpenCode config (defaults to the
- *   standard location).
- * @returns {string} – The API key, or an empty string if not found.
+ * Read the OpenRouter API key from the OpenCode config file.
  */
 export function readOpenRouterApiKeyFromOpenCodeConfig(
   configPath = findOpenCodeConfigPath(),
@@ -165,108 +383,8 @@ export function readOpenRouterApiKeyFromOpenCodeConfig(
   }
 }
 
-/**
- * Fetch the list of currently available free models from OpenRouter.
- * Returns an array sorted by descending capability score.
- * Returns `[]` (with a logged error) if the API key is missing or the request fails.
- * @param {string} apiKey – OpenRouter bearer token.
- * @returns {Promise<Array<{id:string,name:string,contextLength:number,isFree:boolean,score:number}>>}
- */
-export async function pollFreeModels(apiKey) {
-  if (!apiKey) {
-    console.error(
-      "Error: OPENROUTER_API_KEY is not set. Cannot poll free models."
-    );
-    return [];
-  }
-
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-
-  let data;
-  try {
-    const res = await fetch(OPENROUTER_MODELS_URL, {
-      headers: { Authorization: `Bearer ${apiKey}` },
-      signal: controller.signal,
-    });
-    if (!res.ok) {
-      console.error(
-        `Error: OpenRouter models endpoint returned ${res.status} ${res.statusText}`
-      );
-      return [];
-    }
-    data = await res.json();
-  } catch (err) {
-    if (err.name === "AbortError") {
-      console.error(
-        "Error: OpenRouter request timed out after 10 seconds."
-      );
-    } else {
-      console.error(`Error: Failed to fetch OpenRouter models — ${err.message}`);
-    }
-    return [];
-  } finally {
-    clearTimeout(timeout);
-  }
-
-  const models = (data?.data ?? [])
-    .filter(
-      (m) =>
-        m?.pricing?.prompt === "0" && m?.pricing?.completion === "0"
-    )
-    .map((m) => ({
-      id: `openrouter/${m.id}`,
-      name: m.name ?? m.id,
-      contextLength: m.context_length ?? 0,
-      isFree: true,
-    }));
-
-  return models.sort((a, b) => _score(b, "standard") - _score(a, "standard"));
-}
-
-/**
- * Score a model for a given tier (higher is better).
- * @private
- * @param {object} model – Model object as returned by `pollFreeModels`.
- * @param {"reasoning"|"standard"|"fast"} tier – The tier to score for.
- * @returns {number} – Numerical score used for ranking.
- */
-function _score(model, tier) {
-  const { id, contextLength } = model;
-  let score = 0;
-
-  // Context‑length weighting
-  if (contextLength >= 128_000) score += 40;
-  else if (contextLength >= 32_000) score += 20;
-  else if (contextLength >= 16_000) score += 10;
-
-  // Provider‑agnostic capability weighting – no vendor bias
-  if (id.includes("gemma-4")) score += 30;
-  if (id.includes("gemma-3")) score += 25;
-  if (id.includes("gpt-4o")) score += 25;
-  if (id.includes("nemotron-3-super")) score += 20;
-  if (id.includes("llama-3.3-70b")) score += 20;
-  if (id.includes("qwen3") && contextLength >= 32_000) score += 20;
-  if (id.includes("deepseek-r1")) score += 20;
-  if (id.includes("deepseek-v3")) score += 15;
-  // Extra boost for reasoning‑heavy models when the tier is reasoning
-  if (
-    tier === "reasoning" &&
-    (id.includes("deepseek-r1") ||
-      id.includes("nemotron-3-super") ||
-      id.includes("qwen3"))
-  ) {
-    score += 15;
-  }
+// --- Internal helpers ---
 
-  return score;
-}
-
-/**
- * Read CX_MODEL_* assignments from a .env file.
- * @param {string} envPath – Path to the .env file.
- * @returns {{reasoning:any,standard:any,fast:any}} – Current values.
- */
 function readEnvAssignments(envPath) {
   const tierKeys = {
     reasoning: "CX_MODEL_REASONING",
@@ -291,11 +409,6 @@ function readEnvAssignments(envPath) {
   );
 }
 
-/**
- * Extract the primary model ID from a definition that may be a string or an object.
- * @param {string|object} def – Definition to inspect.
- * @returns {string|null} – Primary model ID if found.
- */
 function extractPrimary(def) {
   if (typeof def === "string") return def;
   if (def && typeof def === "object")
@@ -303,21 +416,11 @@ function extractPrimary(def) {
   return null;
 }
 
-/**
- * Build a defaults object from registry‑provided model mappings.
- * Falls back to `BUILTIN_DEFAULTS` when a registry entry is missing.
- * @param {{reasoning:any,standard:any,fast:any}} registryModels – Optional overrides.
- * @returns {{reasoning:string,standard:string,fast:string}} – Resolved defaults.
- */
 function getRegistryDefaults(registryModels = {}) {
   return {
-    reasoning:
-      extractPrimary(registryModels.reasoning) ??
-      BUILTIN_DEFAULTS.reasoning,
-    standard:
-      extractPrimary(registryModels.standard) ??
-      BUILTIN_DEFAULTS.standard,
-    fast: extractPrimary(registryModels.fast) ?? BUILTIN_DEFAULTS.fast,
+    reasoning: extractPrimary(registryModels.reasoning) ?? null,
+    standard: extractPrimary(registryModels.standard) ?? null,
+    fast: extractPrimary(registryModels.fast) ?? null,
   };
 }
 
@@ -351,24 +454,95 @@ function resolveTierDefinition(definition) {
   };
 }
 
+// --- Provider cooldown helpers ---
+
+const PROVIDER_COOLDOWN_MS = 5 * 60 * 1000;
+
+/**
+ * Read the per-provider cooldown state file.
+ * Returns a map of providerKey → expiresAt timestamp.
+ */
+export function readProviderCooldowns(cooldownPath) {
+  try {
+    const raw = fs.readFileSync(cooldownPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return parsed;
+  } catch {
+    // missing or corrupt — treat as empty
+  }
+  return {};
+}
+
+/**
+ * Record a cooldown for a provider key, expiring after PROVIDER_COOLDOWN_MS.
+ */
+export function writeProviderCooldown(cooldownPath, provider, now = Date.now()) {
+  if (!provider) return;
+  const existing = readProviderCooldowns(cooldownPath);
+  existing[provider] = now + PROVIDER_COOLDOWN_MS;
+  fs.mkdirSync(path.dirname(cooldownPath), { recursive: true });
+  fs.writeFileSync(cooldownPath, JSON.stringify(existing, null, 2));
+}
+
+/**
+ * Return true if the given provider is still within its cooldown window.
+ */
+export function isProviderOnCooldown(cooldownPath, provider, now = Date.now()) {
+  if (!provider) return false;
+  const state = readProviderCooldowns(cooldownPath);
+  const expiresAt = state[provider];
+  return typeof expiresAt === "number" && now < expiresAt;
+}
+
+/**
+ * High-level entry point for the fallback hook.
+ *
+ * Given raw hook input, current env path, and a cooldown file path:
+ *   1. Classifies the failure.
+ *   2. Resolves a candidate model from the tier's fallback list, skipping any
+ *      provider currently on cooldown.
+ *   3. Returns { targetModel, tier, reason } or null if nothing actionable.
+ */
+export function selectFallbackModel({
+  hookInput,
+  envPath,
+  cooldownPath,
+  registryModels = {},
+  now = Date.now(),
+} = {}) {
+  const classified = classifyProviderFailure(hookInput);
+  if (!classified || !classified.retryable) return null;
+
+  const failingProvider = providerKey(classified.provider || "");
+  if (failingProvider && isProviderOnCooldown(cooldownPath, failingProvider, now)) return null;
+
+  const currentModels = readCurrentModels(envPath, registryModels);
+  const action = resolveFallbackAction({
+    failure: classified,
+    currentModels,
+    registryModels,
+  });
+  if (!action) return null;
+
+  const candidateProvider = providerKey(action.targetModel);
+  if (candidateProvider && isProviderOnCooldown(cooldownPath, candidateProvider, now)) return null;
+
+  return { targetModel: action.targetModel, tier: action.tier, reason: action.reason };
+}
+
+// --- Public API ---
+
 export function classifyProviderFailure(input) {
   const error = input?.error && typeof input.error === "object" ? input.error : input;
   const text = flattenText([
-    error?.message,
-    error?.name,
-    error?.code,
-    error?.status,
-    error?.statusCode,
-    input?.message,
-    input?.error,
+    error?.message, error?.name, error?.code,
+    error?.status, error?.statusCode,
+    input?.message, input?.error,
   ]);
   if (!text) return null;
 
   const provider = [
-    error?.provider,
-    input?.provider,
-    input?.model?.provider,
-    input?.session?.provider,
+    error?.provider, input?.provider, input?.model?.provider, input?.session?.provider,
   ].find((value) => typeof value === "string" && value) || null;
 
   const patterns = [
@@ -381,11 +555,7 @@ export function classifyProviderFailure(input) {
 
   for (const pattern of patterns) {
     if (pattern.test.test(text)) {
-      return {
-        kind: pattern.kind,
-        provider,
-        retryable: pattern.retryable,
-      };
+      return { kind: pattern.kind, provider, retryable: pattern.retryable };
     }
   }
 
@@ -410,10 +580,7 @@ export function resolveFallbackAction({
   const currentProvider = providerKey(currentModel || "");
   const failingProvider = providerKey(classified.provider || "");
 
-  const candidates = [
-    tierDef.primary,
-    ...tierDef.fallback,
-  ]
+  const candidates = [tierDef.primary, ...tierDef.fallback]
     .filter((modelId) => typeof modelId === "string" && modelId)
     .filter((modelId) => modelId !== currentModel)
     .filter((modelId) => {
@@ -427,43 +594,25 @@ export function resolveFallbackAction({
   const targetModel = candidates[0] ?? null;
   if (!targetModel) return null;
 
-  return {
-    action: "apply-models",
-    reason: classified.kind,
-    targetModel,
-    tier,
-  };
+  return { action: "apply-models", reason: classified.kind, targetModel, tier };
 }
 
 function resolveTierAssignments(envValues = {}, registryModels = {}) {
   const normalizedEnv = normalizeEnvAssignments(envValues);
-  const explicitSources = envValues?.sources && typeof envValues.sources === "object"
-    ? envValues.sources
-    : {};
+  const explicitSources = envValues?.sources && typeof envValues.sources === "object" ? envValues.sources : {};
   const defaults = getRegistryDefaults(registryModels);
   const tiers = {};
 
   for (const tier of ["reasoning", "standard", "fast"]) {
     if (explicitSources[tier]) {
-      tiers[tier] = {
-        model: normalizedEnv[tier] ?? defaults[tier],
-        source: explicitSources[tier],
-      };
-      continue;
-    }
-
-    if (normalizedEnv[tier]) {
-      tiers[tier] = {
-        model: normalizedEnv[tier],
-        source: "env override",
-      };
-      continue;
+      tiers[tier] = { model: normalizedEnv[tier] ?? defaults[tier], source: explicitSources[tier] };
+    } else if (normalizedEnv[tier]) {
+      tiers[tier] = { model: normalizedEnv[tier], source: "env override" };
+    } else if (defaults[tier]) {
+      tiers[tier] = { model: defaults[tier], source: "registry" };
+    } else {
+      tiers[tier] = { model: null, source: "not configured" };
     }
-
-    tiers[tier] = {
-      model: defaults[tier],
-      source: registryModels[tier] ? "registry default" : "built-in default",
-    };
   }
 
   return tiers;
@@ -494,45 +643,6 @@ export function resolveExecutionContractModelMetadata({
   };
 }
 
-/**
- * Check if a model ID ends with `:free`.
- * @param {string} modelId – Model identifier.
- * @returns {boolean} – True if the model is marked as free.
- */
-function isFreeModel(modelId = "") {
-  return /:free$/i.test(modelId);
-}
-
-/**
- * Choose a free model when multiple candidates exist.
- * Preference order: explicit primary > fallback > registry default > builtin default.
- * @param {string} primary – Explicitly selected model.
- * @param {string} fallback – Second‑choice candidate.
- * @param {string} registryDefault – Default from registry.
- * @param {string} builtinDefault – Built‑in fallback.
- * @returns {string|null} – The chosen model ID, or `null` if none selected.
- */
-function preferFreeValue(
-  primary,
-  fallback,
-  registryDefault,
-  builtinDefault
-) {
-  if (primary && isFreeModel(primary)) return primary;
-  if (fallback && isFreeModel(fallback)) return fallback;
-  if (registryDefault && isFreeModel(registryDefault))
-    return registryDefault;
-  if (builtinDefault && isFreeModel(builtinDefault))
-    return builtinDefault;
-  return primary ?? fallback ?? registryDefault ?? builtinDefault ?? null;
-}
-
-/**
- * Infer tier‑specific models from a user‑selected model.
- * @param {string} selectedModel – Model explicitly chosen by the user.
- * @param {{registryModels:object,existing:object}} [options] – Context objects.
- * @returns {{reasoning:string,standard:string,fast:string}|null} – Inferred tier assignments.
- */
 export function inferTierModelsFromSelection(
   selectedModel,
   { registryModels = {}, existing = {} } = {}
@@ -562,53 +672,20 @@ export function inferTierModelsFromSelection(
   };
 }
 
-/**
- * Apply a global “prefer‑free” preference to an existing tier set.
- * @param {{reasoning:string,standard:string,fast:string}} tierSet – Current tier assignments.
- * @param {{registryModels:object}} [options] – Registry context.
- * @returns {{reasoning:string,standard:string,fast:string}} – Updated tier set.
- */
 export function applyFreePreferenceToTierSet(tierSet, { registryModels = {} } = {}) {
   const defaults = getRegistryDefaults(registryModels);
   return {
-    reasoning: preferFreeValue(
-      tierSet.reasoning,
-      tierSet.standard,
-      defaults.reasoning,
-      BUILTIN_DEFAULTS.reasoning
-    ),
-    standard: preferFreeValue(
-      tierSet.standard,
-      tierSet.fast,
-      defaults.standard,
-      BUILTIN_DEFAULTS.standard
-    ),
-    fast: preferFreeValue(
-      tierSet.fast,
-      tierSet.standard,
-      defaults.fast,
-      BUILTIN_DEFAULTS.fast
-    ),
+    reasoning: preferFreeValue(tierSet.reasoning, tierSet.standard, defaults.reasoning, null),
+    standard: preferFreeValue(tierSet.standard, tierSet.fast, defaults.standard, null),
+    fast: preferFreeValue(tierSet.fast, tierSet.standard, defaults.fast, null),
   };
 }
 
-/**
- * Apply “prefer‑free‑same‑family” logic to a tier set based on an explicit
- * model selection. Only swaps a tier to a free sibling if that sibling stays
- * within the same provider family.
- * @param {{reasoning:string,standard:string,fast:string}} tierSet – Current assignments.
- * @param {string} selectedModel – Explicitly selected model ID.
- * @returns {{reasoning:string,standard:string,fast:string}} – Updated tier set.
- */
-export function applyFreeSameFamilyPreferenceToTierSet(
-  tierSet,
-  selectedModel
-) {
+export function applyFreeSameFamilyPreferenceToTierSet(tierSet, selectedModel) {
   const family = matchProviderFamily(selectedModel);
   if (!family) return tierSet;
 
   const sameFamily = family.resolve({ reasoning: null, standard: null, fast: null });
-
   const next = { ...tierSet };
   for (const tier of ["reasoning", "standard", "fast"]) {
     if (tierSet[tier] === selectedModel) continue;
@@ -618,57 +695,6 @@ export function applyFreeSameFamilyPreferenceToTierSet(
   return next;
 }
 
-/**
- * Select the best free model for a given tier from an array of free models.
- * Falls back to a registry‑provided fallback chain if no suitable free model exists.
- * @param {Array} freeModels – Output of `pollFreeModels`.
- * @param {"reasoning"|"standard"|"fast"} tier – Target tier.
- * @param {string[]} [registryFallbacks=[]] – Ordered list of fallback IDs.
- * @returns {string|null} – Best model ID, or `null` if none found.
- */
-export function selectForTier(freeModels, tier, registryFallbacks = []) {
-  const minContext = tier === "fast" ? 8_000 : tier === "standard" ? 16_000 : 32_000;
-
-  if (freeModels && freeModels.length > 0) {
-    const candidates = freeModels
-      .filter((m) => m.contextLength >= minContext)
-      .map((m) => ({ ...m, tierScore: _score(m, tier) }))
-      .sort((a, b) => b.tierScore - a.tierScore);
-
-    if (candidates[0]?.id) return candidates[0].id;
-  }
-
-  // No suitable free model found – walk the registry fallback chain
-  return registryFallbacks[0] ?? null;
-}
-
-/**
- * Return the top N candidates for a given tier (used for UI lists).
- * @param {Array} freeModels – Array of model objects.
- * @param {"reasoning"|"standard"|"fast"} tier – Target tier.
- * @param {number} n – Number of candidates to return (default = 3).
- * @returns {Array} – Sorted candidate objects.
- */
-export function topForTier(freeModels, tier, n = 3) {
-  if (!freeModels || freeModels.length === 0) return [];
-
-  const minContext = tier === "fast" ? 8_000 : tier === "standard" ? 16_000 : 32_000;
-  return freeModels
-    .filter((m) => m.contextLength >= minContext)
-    .map((m) => ({ ...m, tierScore: _score(m, tier) }))
-    .sort((a, b) => b.tierScore - a.tierScore)
-    .slice(0, n);
-}
-
-/**
- * Persist CX_MODEL_* assignments into a .env file.
- *   • Removes any existing comment block that was generated by `--apply`.
- *   • Inserts a fresh comment with the current date.
- *   • Writes the new CX_MODEL_* lines at the top of the file (or appends if the file only contains comments).
- *
- * @param {string} envPath – Path to the .env file.
- * @param {{reasoning?:string,standard?:string,fast?:string}} selections – Model IDs to store.
- */
 export function applyToEnv(envPath, selections) {
   const existing = fs.existsSync(envPath) ? fs.readFileSync(envPath, "utf8") : "";
   const date = new Date().toISOString().slice(0, 10);
@@ -680,7 +706,6 @@ export function applyToEnv(envPath, selections) {
     fast: "CX_MODEL_FAST",
   };
 
-  // Strip out any old auto‑generated block
   let lines = existing.split("\n");
   lines = lines.filter((l) => {
     const trimmed = l.trim();
@@ -690,38 +715,21 @@ export function applyToEnv(envPath, selections) {
     return true;
   });
 
-  // Build the new comment + model lines
   const modelLines = [`${commentMarker} ${date}`];
   for (const [tier, envKey] of Object.entries(tierMap)) {
-    if (selections[tier]) {
-      modelLines.push(`${envKey}=${selections[tier]}`);
-    }
+    if (selections[tier]) modelLines.push(`${envKey}=${selections[tier]}`);
   }
 
-  // Insert just before the first blank line (or at EOF)
   const insertIdx = lines.findLastIndex((l) => l.trim() !== "") + 1;
-  lines.splice(
-    insertIdx === 0 ? lines.length : insertIdx,
-    0,
-    "",
-    ...modelLines
-  );
+  lines.splice(insertIdx === 0 ? lines.length : insertIdx, 0, "", ...modelLines);
 
   fs.writeFileSync(envPath, lines.join("\n"));
 }
 
-/**
- * Remove all CX_MODEL_* entries and their associated comment from a .env file.
- * @param {string} envPath – Path to the .env file.
- */
 export function resetEnv(envPath) {
   if (!fs.existsSync(envPath)) return;
   const commentMarker = "# Auto-set by construct models --apply on";
-  const tierKeys = new Set([
-    "CX_MODEL_REASONING",
-    "CX_MODEL_STANDARD",
-    "CX_MODEL_FAST",
-  ]);
+  const tierKeys = new Set(["CX_MODEL_REASONING", "CX_MODEL_STANDARD", "CX_MODEL_FAST"]);
 
   const lines = fs.readFileSync(envPath, "utf8").split("\n");
   const filtered = lines.filter((l) => {
@@ -735,42 +743,14 @@ export function resetEnv(envPath) {
   fs.writeFileSync(envPath, filtered.join("\n"));
 }
 
-/**
- * Set a single tier’s model in the .env file.
- * @param {string} envPath – Path to the .env file.
- * @param {"reasoning"|"standard"|"fast"} tier – Target tier.
- * @param {string} modelId – Model identifier to store.
- */
 export function setTierModel(envPath, tier, modelId) {
   applyToEnv(envPath, { [tier]: modelId });
 }
 
-/**
- * Replace an existing model selection with a new one, applying any
- * preference‑override flags (`preferFreeSameFamily` or `preferFree`).
- *
- *   applyToEnv() → writes the updated assignments.
- *
- * @param {string} envPath – Path to the .env file.
- * @param {"reasoning"|"standard"|"fast"} tier – Tier whose model should be set.
- * @param {string} modelId – New model ID.
- * @param {{registryModels:object,existing:object}} [context] – Additional context objects.
- * @param {object} [options] – Preference flags.
- * @returns {object} – The resolved tier assignments after overrides.
- */
-export function setModelWithTierInference(
-  envPath,
-  tier,
-  modelId,
-  registryModels = {},
-  options = {}
-) {
+export function setModelWithTierInference(envPath, tier, modelId, registryModels = {}, options = {}) {
   const existing = readEnvAssignments(envPath);
   existing[tier] = modelId;
-  const inferred = inferTierModelsFromSelection(modelId, {
-    registryModels,
-    existing,
-  }) || existing;
+  const inferred = inferTierModelsFromSelection(modelId, { registryModels, existing }) || existing;
   inferred[tier] = modelId;
 
   let resolved = inferred;
@@ -784,13 +764,6 @@ export function setModelWithTierInference(
   return resolved;
 }
 
-/**
- * Read current model assignments from .env, falling back to registry defaults.
- * Provides a source‑tracking map for debugging.
- * @param {string} envPath – Path to the .env file.
- * @param {{reasoning:any,standard:any,fast:any}} registryModels – Reference data.
- * @returns {{reasoning:string,standard:string,fast:string,sources:Record<string,string>>}
- */
 export function readCurrentModels(envPath, registryModels = {}) {
   const envValues = arguments.length > 2 ? arguments[2] : {};
   const fileAssignments = readEnvAssignments(envPath);
@@ -808,3 +781,6 @@ export function readCurrentModels(envPath, registryModels = {}) {
   }
   return result;
 }
+
+export { resolveProviderCapabilities } from './provider-capabilities.js';
+export { resolveProviderCapabilitiesSync } from './provider-capabilities.js';