@geraldmaron/construct 1.1.1 → 1.2.1

package/lib/model-router.mjs

@@ -24,6 +24,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "child_process";
+import { hasAnySecret } from "./providers/secret-resolver.mjs";
+import { isOllamaModelInstalled, toOllamaNativeModelId } from "./ollama/installed-models.mjs";
+import { readRawFromOpenCodeProvider } from "./providers/credential-sources.mjs";
 import { findOpenCodeConfigPath } from "./opencode-config.mjs";
 import { isLocalModel } from "./mcp/tool-budget.mjs";
 import {
@@ -33,6 +36,11 @@ import {
   selectForTier,
   topForTier,
 } from "./model-free-selector.mjs";
+import {
+  applyModelVisibilityFilter,
+  loadModelsCatalogContext,
+  mergeLiveModelsIntoProviders,
+} from "./models/catalog.mjs";
 
 function uniqueStrings(values = []) {
   return [...new Set(values.filter((value) => typeof value === "string" && value.trim()))];
@@ -100,6 +108,10 @@ function inferSmallModelProfile(selectedModel) {
   return false;
 }
 
+// Temporary compatibility fallback (construct-6zga.1.8): the ExecutionCapabilityProfile
+// records this profile id as source 'compatibility_fallback'; specialist composition
+// consumes the profile, not this function directly.
+
 export function resolveModelOperatingProfile({
   envValues = {},
   selectedModel = null,
@@ -118,6 +130,10 @@ export function resolveModelOperatingProfile({
 // comply with — floor (must-keep only), mid, or full. A COLLAPSED probe verdict forces
 // floor; otherwise local size estimates the tier and any cloud model gets the full
 // persona, so cloud configs are never slimmed.
+//
+// Temporary compatibility fallback (construct-6zga.1.8): this name/size heuristic is
+// the fallback the ExecutionCapabilityProfile records as source 'compatibility_fallback'
+// when no measured evidence exists. Consumers read the profile, not this directly.
 
 export function resolveCapabilityTier({ model, verdict = null } = {}) {
   if (!isLocalModel(model)) return 'full';
@@ -196,12 +212,12 @@ const PROVIDER_FAMILY_TIERS = [
     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",
+      fast: fast ?? "openrouter/google/gemini-2.0-flash-001",
     }),
     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"],
+      fast: ["openrouter/google/gemini-2.0-flash-001", "openrouter/google/gemma-4-26b-a4b-it:free"],
     },
   },
   {
@@ -239,14 +255,14 @@ const PROVIDER_FAMILY_TIERS = [
     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",
+      reasoning: reasoning ?? "github-copilot/gpt-5.5",
+      standard: standard ?? "github-copilot/gpt-5.4",
+      fast: fast ?? "github-copilot/gpt-5.4-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"],
+      reasoning: ["github-copilot/gpt-5.5", "github-copilot/gpt-5.4", "github-copilot/claude-opus-4.8"],
+      standard: ["github-copilot/gpt-5.4", "github-copilot/gpt-4o", "github-copilot/claude-sonnet-4.6"],
+      fast: ["github-copilot/gpt-5.4-mini", "github-copilot/gpt-4o-mini"],
     },
   },
   {
@@ -282,6 +298,21 @@ const PROVIDER_FAMILY_TIERS = [
       fast: ["openrouter/meta-llama/llama-3.3-70b-instruct:free", "openrouter/meta-llama/llama-3.3-70b-instruct"],
     },
   },
+  {
+    id: 'openrouter',
+    label: 'OpenRouter (general)',
+    test: (modelId) => /^openrouter\//.test(modelId),
+    resolve: ({ reasoning, standard, fast }) => ({
+      reasoning: reasoning ?? "openrouter/qwen/qwen3-coder",
+      standard: standard ?? "openrouter/qwen/qwen3-coder:free",
+      fast: fast ?? "openrouter/qwen/qwen3-coder:free",
+    }),
+    options: {
+      reasoning: ["openrouter/openrouter/free", "openrouter/qwen/qwen3-coder", "openrouter/deepseek/deepseek-r1"],
+      standard: ["openrouter/openrouter/free", "openrouter/qwen/qwen3-coder:free", "openrouter/google/gemini-2.0-flash-001"],
+      fast: ["openrouter/openrouter/free", "openrouter/qwen/qwen3-coder:free", "openrouter/meta-llama/llama-3.3-70b-instruct:free"],
+    },
+  },
   {
     id: 'ollama',
     label: 'Ollama (local)',
@@ -335,15 +366,46 @@ const PROVIDER_ENV_MAP = {
   'github-copilot': ['GITHUB_TOKEN', 'GH_TOKEN'],
   'openai': ['OPENAI_API_KEY'],
   'openrouter-llama': ['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'],
+  'openrouter': ['OPENROUTER_API_KEY', 'OPEN_ROUTER_API_KEY'],
   'ollama': ['OLLAMA_BASE_URL', 'OLLAMA_HOST'],
   'local': ['LOCAL_LLM_BASE_URL'],
 };
 
+// A stored device-flow Copilot credential — Construct's own auth store or the
+// standard ~/.config/github-copilot store other tools share — means Copilot is
+// usable without a gh CLI session. Detection stays sync, file-only, and never
+// performs the token exchange; copilot-auth.mjs owns read/write/refresh.
+
+function hasCopilotCredential() {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  if (!home) return false;
+  const candidates = [
+    path.join(home, '.construct', 'auth', 'github-copilot.json'),
+    path.join(home, '.config', 'github-copilot', 'apps.json'),
+    path.join(home, '.config', 'github-copilot', 'hosts.json'),
+  ];
+  for (const file of candidates) {
+    try {
+      if (!fs.existsSync(file)) continue;
+      const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+      if (file.endsWith('github-copilot.json')) {
+        if (data && (data.oauth_token || data.token || data.refresh_token || data.refresh)) return true;
+      } else {
+        for (const entry of Object.values(data || {})) {
+          if (entry && (entry.oauth_token || entry.token)) return true;
+        }
+      }
+    } catch { /* unreadable or non-JSON is not a usable credential */ }
+  }
+  return false;
+}
+
 /**
  * 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.
+ * Uses the passed env, dotenv files, shell rc, then the Copilot credential store
+ * or gh CLI for Copilot. A stored op:// reference counts as configured.
  */
-function isProviderConfigured(familyId, env) {
+function isProviderConfigured(familyId, env, { allowAmbient = true } = {}) {
   const varNames = PROVIDER_ENV_MAP[familyId];
   if (!varNames?.length) return false;
 
@@ -359,71 +421,31 @@ function isProviderConfigured(familyId, env) {
     } catch { /* not available */ }
   }
 
-  // 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;
+  // Any credential source counts — env, ~/.construct/config.env, ~/.env, the
+  // project .env, and shell rc exports — and a stored 1Password op:// reference
+  // counts as configured because the resolver reads it lazily at call time.
+  if (hasAnySecret(varNames, { env, allowAmbient })) return true;
 
-  // 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 */ }
-
-  // GitHub Copilot: detect via gh CLI auth status
+  // GitHub Copilot authenticates via OAuth rather than an API key: a stored
+  // device-flow credential, or a gh CLI session as a fallback, both count.
   if (familyId === 'github-copilot') {
+    if (hasCopilotCredential()) return true;
     try {
       const r = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8', timeout: 3000 });
       return r.status === 0;
     } catch { return false; }
   }
 
-  // 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 */ }
-
-  // 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) => {
+export function getProviderModelCatalog({
+  env = process.env,
+  cwd = process.cwd(),
+  activeModelId = null,
+  registryModels: registryModelsOverride = null,
+} = {}) {
+  const baseProviders = PROVIDER_FAMILY_TIERS.map((family) => {
     const tiers = family.resolve({});
     const options = {
       reasoning: uniqueStrings([...(family.options?.reasoning ?? []), tiers.reasoning]),
@@ -442,13 +464,195 @@ export function getProviderModelCatalog({ env = process.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)),
+  const { modelsConfig, registryModels, liveModels } = loadModelsCatalogContext({ cwd, env });
+  const mergedProviders = mergeLiveModelsIntoProviders(
+    baseProviders,
+    liveModels,
+    { maxLiveFree: modelsConfig.catalog.maxLiveFree },
+  );
+
+  const tierOptionsRaw = {
+    reasoning: uniqueStrings(mergedProviders.flatMap((provider) => provider.options.reasoning)),
+    standard: uniqueStrings(mergedProviders.flatMap((provider) => provider.options.standard)),
+    fast: uniqueStrings(mergedProviders.flatMap((provider) => provider.options.fast)),
   };
 
-  return { providers, tierOptions };
+  return applyModelVisibilityFilter(
+    { providers: mergedProviders, tierOptions: tierOptionsRaw },
+    {
+      visibility: modelsConfig.visibility,
+      registryModels: registryModelsOverride ?? registryModels,
+      activeModelId,
+    },
+  );
+}
+
+// Provider families with open-ended model catalogs: credential presence is the
+// gate; static option lists are hints, not exhaustive allowlists.
+
+const LENIENT_MODEL_FAMILIES = new Set([
+  'openrouter-anthropic',
+  'openrouter-google',
+  'openrouter-deepseek',
+  'openrouter-qwen',
+  'openrouter-llama',
+  'openrouter',
+  'openai',
+  'anthropic',
+  'ollama',
+  'local',
+]);
+
+/**
+ * Check whether a model id can be used on this machine right now: the provider
+ * family must match, credentials must be present (including op:// and Copilot
+ * auth-store), and for fixed-catalog families (e.g. github-copilot) the id must
+ * appear in the shipped option list or tier defaults — not a stale CX_MODEL pin.
+ */
+export function isChatModelAvailable(modelId, { env = process.env, excludeFamilies = [] } = {}) {
+  if (!modelId || typeof modelId !== 'string') {
+    return { ok: false, reason: 'missing', modelId: modelId || null };
+  }
+  const family = matchProviderFamily(modelId);
+  if (!family) {
+    return { ok: false, reason: 'unknown_family', modelId };
+  }
+  if (excludeFamilies.includes(family.id)) {
+    return { ok: false, reason: 'excluded', modelId, provider: family.id };
+  }
+  if (!isProviderConfigured(family.id, env)) {
+    return { ok: false, reason: 'provider_not_configured', modelId, provider: family.id };
+  }
+  if (family.id === 'ollama') {
+    const nativeModel = toOllamaNativeModelId(modelId);
+    const installed = isOllamaModelInstalled(modelId, { env });
+    if (installed === true) {
+      return { ok: true, modelId, provider: family.id };
+    }
+    if (installed === false) {
+      return {
+        ok: false,
+        reason: 'model_not_pulled',
+        modelId,
+        provider: family.id,
+        nativeModel,
+        pullCommand: `ollama pull ${nativeModel}`,
+      };
+    }
+    return { ok: true, modelId, provider: family.id };
+  }
+  if (LENIENT_MODEL_FAMILIES.has(family.id)) {
+    return { ok: true, modelId, provider: family.id };
+  }
+  const { providers } = getProviderModelCatalog({ env });
+  const provider = providers.find((p) => p.id === family.id);
+  if (!provider) {
+    return { ok: false, reason: 'unknown_family', modelId };
+  }
+  const known = uniqueStrings([
+    ...(provider.options?.reasoning ?? []),
+    ...(provider.options?.standard ?? []),
+    ...(provider.options?.fast ?? []),
+    provider.tiers?.reasoning,
+    provider.tiers?.standard,
+    provider.tiers?.fast,
+  ]);
+  if (known.includes(modelId)) {
+    return { ok: true, modelId, provider: family.id };
+  }
+  return { ok: false, reason: 'model_not_available', modelId, provider: family.id };
+}
+
+function availabilityNotice(rejected) {
+  if (!rejected?.modelId) return null;
+  const label = rejected.modelId;
+  if (rejected.reason === 'provider_not_configured') {
+    const family = rejected.provider || '';
+    if (family.startsWith('openrouter')) {
+      return `Saved ${label} — OpenRouter not configured. Set OPENROUTER_API_KEY in ~/.construct/config.env or run \`construct creds set openrouter\`.`;
+    }
+    return `Saved ${label} — provider not configured.`;
+  }
+  if (rejected.reason === 'model_not_available') {
+    return `Pinned ${label} — not available on your account.`;
+  }
+  if (rejected.reason === 'model_not_pulled') {
+    const native = rejected.nativeModel || toOllamaNativeModelId(label);
+    return `Pinned ${label} — not installed locally. Run \`ollama pull ${native}\` or \`construct ollama pull ${native}\`.`;
+  }
+  if (rejected.reason === 'unknown_family') {
+    return `Pinned ${label} — unrecognized model id.`;
+  }
+  return `Pinned ${label} — unavailable.`;
+}
+
+function recommendTierModel(tier, { env = process.env, excludeFamilies = [] } = {}) {
+  const { providers } = getProviderModelCatalog({ env });
+  for (const provider of providers) {
+    if (!provider.configured || excludeFamilies.includes(provider.id)) continue;
+    const candidates = uniqueStrings([
+      provider.tiers?.[tier],
+      ...(provider.options?.[tier] ?? []),
+    ]);
+    for (const id of candidates) {
+      const check = isChatModelAvailable(id, { env, excludeFamilies });
+      if (check.ok) return { id, provider: provider.label, tier };
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the chat model with validation: explicit request and CX_MODEL pins
+ * are preferences, not blind truth. Stale or unconfigured pins fall through to
+ * the next configured provider for the tier, with a human-readable notice.
+ */
+export function resolveValidatedChatModel({ env = process.env, requested = null, excludeFamilies = [] } = {}) {
+  const rejections = [];
+
+  if (requested) {
+    const check = isChatModelAvailable(requested, { env, excludeFamilies });
+    if (check.ok) {
+      return { id: requested, source: 'explicit', notice: null, rejected: [] };
+    }
+    rejections.push(check);
+  }
+
+  const pinOrder = [
+    ['standard', env.CX_MODEL_STANDARD],
+    ['reasoning', env.CX_MODEL_REASONING],
+    ['fast', env.CX_MODEL_FAST],
+  ];
+  for (const [tier, pin] of pinOrder) {
+    if (!pin) continue;
+    const check = isChatModelAvailable(pin, { env, excludeFamilies });
+    if (check.ok) {
+      const notice = rejections.length
+        ? `${availabilityNotice(rejections[0])} Using ${pin}.`
+        : null;
+      return { id: pin, source: 'pin', tier, notice, rejected: rejections };
+    }
+    rejections.push(check);
+  }
+
+  const standard = recommendTierModel('standard', { env, excludeFamilies });
+  if (standard) {
+    const notice = rejections.length
+      ? `${availabilityNotice(rejections[0])} Using ${standard.id} (${standard.provider}).`
+      : null;
+    return { id: standard.id, source: 'recommended', tier: 'standard', notice, rejected: rejections };
+  }
+
+  const anyTier = recommendTierModel('reasoning', { env, excludeFamilies }) || recommendTierModel('fast', { env, excludeFamilies });
+  if (anyTier) {
+    const notice = rejections.length
+      ? `${availabilityNotice(rejections[0])} Using ${anyTier.id} (${anyTier.provider}).`
+      : null;
+    return { id: anyTier.id, source: 'recommended', tier: anyTier.tier, notice, rejected: rejections };
+  }
+
+  const notice = rejections.length ? availabilityNotice(rejections[0]) : null;
+  return { id: null, source: null, notice, rejected: rejections };
 }
 
 /**
@@ -473,13 +677,10 @@ export function resolveTiersForPrimary(primaryModelId) {
 // callers (embedded model resolution, capability discovery) stay synchronous
 // and deterministic, and never expose a key value, only its presence.
 
-function familyDescriptor(family, env) {
+function familyDescriptor(family, env, { allowAmbient = true } = {}) {
   const requiresEnv = PROVIDER_ENV_MAP[family.id] || (Array.isArray(family.requiresEnv) ? family.requiresEnv : []);
   const local = family.local === true;
-  const configured = local || requiresEnv.some((key) => {
-    const value = env?.[key];
-    return typeof value === "string" && value.length > 0;
-  });
+  const configured = isProviderConfigured(family.id, env, { allowAmbient });
   return {
     id: family.id,
     label: family.label,
@@ -495,18 +696,18 @@ function familyDescriptor(family, env) {
  * confirm credentials and whether they are present. Returns null when no family
  * matches.
  */
-export function describeModelFamily(modelId, { env = process.env } = {}) {
+export function describeModelFamily(modelId, { env = process.env, allowAmbient = true } = {}) {
   const family = matchProviderFamily(modelId);
   if (!family) return null;
-  return familyDescriptor(family, env);
+  return familyDescriptor(family, env, { allowAmbient });
 }
 
 /**
  * Describe every provider family. Resolves a host-supplied provider id and
  * enumerates model availability for the embedded contract layer.
  */
-export function listModelFamilies({ env = process.env } = {}) {
-  return PROVIDER_FAMILY_TIERS.map((family) => familyDescriptor(family, env));
+export function listModelFamilies({ env = process.env, allowAmbient = true } = {}) {
+  return PROVIDER_FAMILY_TIERS.map((family) => familyDescriptor(family, env, { allowAmbient }));
 }
 
 /**
@@ -515,17 +716,7 @@ export function listModelFamilies({ env = process.env } = {}) {
 export function readOpenRouterApiKeyFromOpenCodeConfig(
   configPath = findOpenCodeConfigPath(),
 ) {
-  try {
-    if (!fs.existsSync(configPath)) return "";
-    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
-    const auth = config?.provider?.openrouter?.options?.headers?.Authorization;
-    if (typeof auth !== "string") return "";
-    const value = auth.replace(/^Bearer\s+/i, "").trim();
-    if (!value || value.includes("__OPENROUTER_API_KEY__")) return "";
-    return value;
-  } catch {
-    return "";
-  }
+  return readRawFromOpenCodeProvider('openrouter', configPath) || "";
 }
 
 // --- Internal helpers ---
@@ -571,9 +762,18 @@ function getRegistryDefaults(registryModels = {}) {
 
 function normalizeEnvAssignments(envValues = {}) {
   return {
-    reasoning: envValues.reasoning ?? envValues.CX_MODEL_REASONING ?? null,
-    standard: envValues.standard ?? envValues.CX_MODEL_STANDARD ?? null,
-    fast: envValues.fast ?? envValues.CX_MODEL_FAST ?? null,
+    reasoning: envValues.reasoning
+      ?? envValues.CX_MODEL_REASONING
+      ?? envValues.CONSTRUCT_MODEL_REASONING
+      ?? null,
+    standard: envValues.standard
+      ?? envValues.CX_MODEL_STANDARD
+      ?? envValues.CONSTRUCT_MODEL_STANDARD
+      ?? null,
+    fast: envValues.fast
+      ?? envValues.CX_MODEL_FAST
+      ?? envValues.CONSTRUCT_MODEL_FAST
+      ?? null,
   };
 }
 
@@ -914,6 +1114,87 @@ export function setModelWithTierInference(envPath, tier, modelId, registryModels
   return resolved;
 }
 
+export function resolveModelTiers(options = {}) {
+  const {
+    env = process.env,
+    registryPath = null,
+    strict = false,
+  } = options;
+
+  let registryModels = {};
+  if (registryPath && fs.existsSync(registryPath)) {
+    try {
+      const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      registryModels = registry.models ?? {};
+    } catch (err) {
+      return {
+        models: { reasoning: null, standard: null, fast: null },
+        sources: { reasoning: 'not configured', standard: 'not configured', fast: 'not configured' },
+        configured: 0,
+        complete: false,
+        errors: [`Failed to read registry: ${err.message}`],
+      };
+    }
+  }
+
+  const tiers = resolveTierAssignments(normalizeEnvAssignments(env), registryModels);
+  const models = {};
+  const sources = {};
+  for (const tier of ['reasoning', 'standard', 'fast']) {
+    models[tier] = tiers[tier].model;
+    sources[tier] = tiers[tier].source;
+  }
+  const configured = Object.values(models).filter(Boolean).length;
+  const errors = strict && configured < 3
+    ? [`Missing configuration for tiers: ${['reasoning', 'standard', 'fast'].filter((t) => !models[t]).join(', ')}`]
+    : null;
+
+  return {
+    models,
+    sources,
+    configured,
+    complete: configured === 3,
+    errors,
+  };
+}
+
+export function getModelForTier(tier, options = {}) {
+  return resolveModelTiers(options).models[tier];
+}
+
+export function getModelSource(tier, options = {}) {
+  return resolveModelTiers(options).sources[tier] || 'unknown';
+}
+
+export function validateModelTiers(options = {}) {
+  const resolved = resolveModelTiers({ ...options, strict: true });
+  const unconfigured = Object.entries(resolved.sources)
+    .filter(([, source]) => source === 'not configured')
+    .map(([tier]) => tier);
+
+  return {
+    valid: resolved.complete && !resolved.errors,
+    errors: resolved.errors,
+    warnings: unconfigured.length > 0
+      ? [`Unconfigured tier${unconfigured.length === 1 ? '' : 's'}: ${unconfigured.join(', ')}. Run 'construct models --apply' or set CX_MODEL_<TIER>.`]
+      : [],
+    resolution: resolved,
+  };
+}
+
+export function formatModelStatus(options = {}) {
+  const resolved = resolveModelTiers(options);
+  let output = 'Model Configuration:\n\n';
+  for (const tier of ['reasoning', 'standard', 'fast']) {
+    const model = resolved.models[tier];
+    const source = resolved.sources[tier];
+    const icon = source === 'not configured' ? '!' : 'ok';
+    output += `${icon} ${tier.padEnd(10)} ${model ?? '(not configured)'}\n`;
+    output += `  Source: ${source}\n\n`;
+  }
+  return output;
+}
+
 export function readCurrentModels(envPath, registryModels = {}) {
   const envValues = arguments.length > 2 ? arguments[2] : {};
   const fileAssignments = readEnvAssignments(envPath);