@ran-sh/dsh-crew 1.9.0 → 1.10.0

package/src/model-callability-contract.mjs

@@ -1,79 +1,79 @@
-import { isExactNativeCrewIdentity, sameCompleteRuntimeIdentity } from './runtime-identity-contract.mjs';
-
-export const MODEL_CALLABILITY_SCHEMA_VERSION = 2;
-const ROLES = ['worker', 'reviewer'];
-const STATES = new Set(['CALLABLE', 'NOT_CALLABLE', 'STALE', 'UNKNOWN', 'NOT_APPLICABLE']);
-const SOURCES = new Set(['provider_health', 'execution']);
-const MAX_EVIDENCE_TTL_MS = 24 * 60 * 60 * 1000;
-
-function exactKeys(value, keys) {
-  return value && typeof value === 'object' && !Array.isArray(value)
-    && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
-}
-
-function route(value) {
-  return typeof value?.provider === 'string' && value.provider.trim()
-    && typeof value?.model === 'string' && value.model.trim()
-    ? { provider: value.provider.trim(), model: value.model.trim() } : null;
-}
-
-function validEvidence(role, now) {
-  if (!SOURCES.has(role.source) || !Number.isFinite(role.observed_at) || role.observed_at > now
-    || !Number.isFinite(role.expires_at) || role.expires_at <= now
-    || role.expires_at - role.observed_at > MAX_EVIDENCE_TTL_MS) return false;
-  if (role.source === 'execution') {
-    if (!role.last_success || typeof role.last_success !== 'object'
-      || typeof role.last_success.job_id !== 'string' || !role.last_success.job_id.trim()
-      || role.last_success.observed_at !== role.observed_at
-      || role.last_success.expires_at !== role.expires_at) return false;
-  }
-  return true;
-}
-
-export function validateModelCallabilityV2({ projection, runtime, expectedEnabledRoles, expectedSelections, now = Date.now() } = {}) {
-  const fail = (reason_code) => ({ ok: false, reason_code, state: 'UNKNOWN' });
-  if (!projection || typeof projection !== 'object' || projection.schema_version !== MODEL_CALLABILITY_SCHEMA_VERSION) return fail('MODEL_CALLABILITY_SCHEMA_INVALID');
-  if (!isExactNativeCrewIdentity(runtime) || !isExactNativeCrewIdentity(projection.runtime_identity)
-    || !sameCompleteRuntimeIdentity(runtime, projection.runtime_identity)
-    || projection.current_runtime_id !== runtime.runtime_id) return fail('MODEL_CALLABILITY_RUNTIME_MISMATCH');
-  if (!Number.isFinite(projection.captured_at) || projection.captured_at > now) return fail('MODEL_CALLABILITY_CAPTURE_INVALID');
-  if (!exactKeys(projection.enabled_roles, ROLES) || ROLES.some((role) => typeof projection.enabled_roles[role] !== 'boolean')) return fail('MODEL_CALLABILITY_ROLES_INVALID');
-  if (expectedEnabledRoles && (!exactKeys(expectedEnabledRoles, ROLES) || ROLES.some((role) => projection.enabled_roles[role] !== expectedEnabledRoles[role]))) return fail('MODEL_CALLABILITY_ROLE_CONFIG_MISMATCH');
-  if (expectedSelections && !exactKeys(expectedSelections, ROLES)) return fail('MODEL_CALLABILITY_EXPECTED_SELECTIONS_INVALID');
-  if (!exactKeys(projection.roles, ROLES)) return fail('MODEL_CALLABILITY_ROLE_EVIDENCE_MISSING');
-
-  for (const roleName of ROLES) {
-    const role = projection.roles[roleName];
-    if (!role || !STATES.has(role.state)) return fail('MODEL_CALLABILITY_ROLE_STATE_INVALID');
-    const selected = route(role.selected);
-    if (role.selected !== undefined && role.selected !== null && !selected) return fail('MODEL_CALLABILITY_SELECTION_INVALID');
-    if (expectedSelections) {
-      const expectedRaw = expectedSelections[roleName];
-      const expected = expectedRaw === null ? null : route(expectedRaw);
-      if (expectedRaw !== null && !expected) return fail('MODEL_CALLABILITY_EXPECTED_SELECTION_INVALID');
-      if ((expected === null) !== (selected === null)
-        || expected && (expected.provider !== selected.provider || expected.model !== selected.model)) return fail('MODEL_CALLABILITY_SELECTION_MISMATCH');
-    }
-    if (projection.enabled_roles[roleName] === false) {
-      if (role.state !== 'NOT_APPLICABLE' || role.reason_code !== 'ROLE_DISABLED') return fail('MODEL_CALLABILITY_DISABLED_ROLE_INVALID');
-      continue;
-    }
-    if (['CALLABLE', 'NOT_CALLABLE'].includes(role.state) && !selected) return fail('MODEL_CALLABILITY_SELECTION_INVALID');
-    if (projection.enabled_roles[roleName] === true && role.state === 'NOT_APPLICABLE') return fail('MODEL_CALLABILITY_ENABLED_ROLE_NOT_APPLICABLE');
-    if (['CALLABLE', 'NOT_CALLABLE'].includes(role.state)) {
-      if (!validEvidence(role, now)) return fail('MODEL_CALLABILITY_EVIDENCE_INVALID');
-    }
-  }
-
-  const activeRoles = ROLES.map((role) => projection.roles[role]).filter((_, index) => projection.enabled_roles[ROLES[index]] === true);
-  const activeStates = activeRoles.map((role) => role.state);
-  const state = activeStates.includes('NOT_CALLABLE') ? 'NOT_CALLABLE'
-    : activeStates.length > 0 && activeStates.every((value) => value === 'CALLABLE') ? 'CALLABLE'
-      : activeStates.includes('STALE') ? 'STALE' : 'UNKNOWN';
-  if (projection.overall !== state) return fail('MODEL_CALLABILITY_OVERALL_CONTRADICTION');
-  const evidenceExpirations = activeRoles.map((role) => role.expires_at).filter((value) => Number.isFinite(value));
-  const expectedExpires = evidenceExpirations.length ? Math.min(...evidenceExpirations) : null;
-  if (projection.expires_at !== expectedExpires) return fail('MODEL_CALLABILITY_EXPIRY_CONTRADICTION');
-  if (state === 'CALLABLE' && (!Number.isFinite(projection.expires_at) || projection.expires_at <= now)) return fail('MODEL_CALLABILITY_EXPIRED');
-  return { ok: true, state, reason_code: 'MODEL_CALLABILITY_VALID' };
-}
+import { isExactNativeCrewIdentity, sameCompleteRuntimeIdentity } from './runtime-identity-contract.mjs';
+
+export const MODEL_CALLABILITY_SCHEMA_VERSION = 2;
+const ROLES = ['worker', 'reviewer'];
+const STATES = new Set(['CALLABLE', 'NOT_CALLABLE', 'STALE', 'UNKNOWN', 'NOT_APPLICABLE']);
+const SOURCES = new Set(['provider_health', 'execution']);
+const MAX_EVIDENCE_TTL_MS = 24 * 60 * 60 * 1000;
+
+function exactKeys(value, keys) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+
+function route(value) {
+  return typeof value?.provider === 'string' && value.provider.trim()
+    && typeof value?.model === 'string' && value.model.trim()
+    ? { provider: value.provider.trim(), model: value.model.trim() } : null;
+}
+
+function validEvidence(role, now) {
+  if (!SOURCES.has(role.source) || !Number.isFinite(role.observed_at) || role.observed_at > now
+    || !Number.isFinite(role.expires_at) || role.expires_at <= now
+    || role.expires_at - role.observed_at > MAX_EVIDENCE_TTL_MS) return false;
+  if (role.source === 'execution') {
+    if (!role.last_success || typeof role.last_success !== 'object'
+      || typeof role.last_success.job_id !== 'string' || !role.last_success.job_id.trim()
+      || role.last_success.observed_at !== role.observed_at
+      || role.last_success.expires_at !== role.expires_at) return false;
+  }
+  return true;
+}
+
+export function validateModelCallabilityV2({ projection, runtime, expectedEnabledRoles, expectedSelections, now = Date.now() } = {}) {
+  const fail = (reason_code) => ({ ok: false, reason_code, state: 'UNKNOWN' });
+  if (!projection || typeof projection !== 'object' || projection.schema_version !== MODEL_CALLABILITY_SCHEMA_VERSION) return fail('MODEL_CALLABILITY_SCHEMA_INVALID');
+  if (!isExactNativeCrewIdentity(runtime) || !isExactNativeCrewIdentity(projection.runtime_identity)
+    || !sameCompleteRuntimeIdentity(runtime, projection.runtime_identity)
+    || projection.current_runtime_id !== runtime.runtime_id) return fail('MODEL_CALLABILITY_RUNTIME_MISMATCH');
+  if (!Number.isFinite(projection.captured_at) || projection.captured_at > now) return fail('MODEL_CALLABILITY_CAPTURE_INVALID');
+  if (!exactKeys(projection.enabled_roles, ROLES) || ROLES.some((role) => typeof projection.enabled_roles[role] !== 'boolean')) return fail('MODEL_CALLABILITY_ROLES_INVALID');
+  if (expectedEnabledRoles && (!exactKeys(expectedEnabledRoles, ROLES) || ROLES.some((role) => projection.enabled_roles[role] !== expectedEnabledRoles[role]))) return fail('MODEL_CALLABILITY_ROLE_CONFIG_MISMATCH');
+  if (expectedSelections && !exactKeys(expectedSelections, ROLES)) return fail('MODEL_CALLABILITY_EXPECTED_SELECTIONS_INVALID');
+  if (!exactKeys(projection.roles, ROLES)) return fail('MODEL_CALLABILITY_ROLE_EVIDENCE_MISSING');
+
+  for (const roleName of ROLES) {
+    const role = projection.roles[roleName];
+    if (!role || !STATES.has(role.state)) return fail('MODEL_CALLABILITY_ROLE_STATE_INVALID');
+    const selected = route(role.selected);
+    if (role.selected !== undefined && role.selected !== null && !selected) return fail('MODEL_CALLABILITY_SELECTION_INVALID');
+    if (expectedSelections) {
+      const expectedRaw = expectedSelections[roleName];
+      const expected = expectedRaw === null ? null : route(expectedRaw);
+      if (expectedRaw !== null && !expected) return fail('MODEL_CALLABILITY_EXPECTED_SELECTION_INVALID');
+      if ((expected === null) !== (selected === null)
+        || expected && (expected.provider !== selected.provider || expected.model !== selected.model)) return fail('MODEL_CALLABILITY_SELECTION_MISMATCH');
+    }
+    if (projection.enabled_roles[roleName] === false) {
+      if (role.state !== 'NOT_APPLICABLE' || role.reason_code !== 'ROLE_DISABLED') return fail('MODEL_CALLABILITY_DISABLED_ROLE_INVALID');
+      continue;
+    }
+    if (['CALLABLE', 'NOT_CALLABLE'].includes(role.state) && !selected) return fail('MODEL_CALLABILITY_SELECTION_INVALID');
+    if (projection.enabled_roles[roleName] === true && role.state === 'NOT_APPLICABLE') return fail('MODEL_CALLABILITY_ENABLED_ROLE_NOT_APPLICABLE');
+    if (['CALLABLE', 'NOT_CALLABLE'].includes(role.state)) {
+      if (!validEvidence(role, now)) return fail('MODEL_CALLABILITY_EVIDENCE_INVALID');
+    }
+  }
+
+  const activeRoles = ROLES.map((role) => projection.roles[role]).filter((_, index) => projection.enabled_roles[ROLES[index]] === true);
+  const activeStates = activeRoles.map((role) => role.state);
+  const state = activeStates.includes('NOT_CALLABLE') ? 'NOT_CALLABLE'
+    : activeStates.length > 0 && activeStates.every((value) => value === 'CALLABLE') ? 'CALLABLE'
+      : activeStates.includes('STALE') ? 'STALE' : 'UNKNOWN';
+  if (projection.overall !== state) return fail('MODEL_CALLABILITY_OVERALL_CONTRADICTION');
+  const evidenceExpirations = activeRoles.map((role) => role.expires_at).filter((value) => Number.isFinite(value));
+  const expectedExpires = evidenceExpirations.length ? Math.min(...evidenceExpirations) : null;
+  if (projection.expires_at !== expectedExpires) return fail('MODEL_CALLABILITY_EXPIRY_CONTRADICTION');
+  if (state === 'CALLABLE' && (!Number.isFinite(projection.expires_at) || projection.expires_at <= now)) return fail('MODEL_CALLABILITY_EXPIRED');
+  return { ok: true, state, reason_code: 'MODEL_CALLABILITY_VALID' };
+}

package/src/model-catalog.mjs

@@ -1,180 +1,180 @@
-// Read-only adapter from the DSH LLM registry to a credential-free Settings
-// payload. Provider/model discovery stays owned by Harness; Crew only reads
-// its registered routes and advertised catalog.
-
-export const MODEL_CATALOG_UNAVAILABLE = 'MODEL_CATALOG_UNAVAILABLE';
-
-export const CATALOG_HEALTH_CODES = Object.freeze({
-  EMPTY_CATALOG: 'EMPTY_CATALOG',
-  EMPTY_PROVIDER_MODELS: 'EMPTY_PROVIDER_MODELS',
-  PROVIDER_MODEL_LIST_FAILED: 'PROVIDER_MODEL_LIST_FAILED',
-  HARNESS_DEFAULT_PROVIDER_MISSING: 'HARNESS_DEFAULT_PROVIDER_MISSING',
-  HARNESS_DEFAULT_MODEL_UNADVERTISED: 'HARNESS_DEFAULT_MODEL_UNADVERTISED',
-  CATALOG_CONSTRAINED: 'CATALOG_CONSTRAINED',
-});
-
-function catalogError() {
-  return Object.assign(new Error('Unable to read Harness model catalog.'), { code: MODEL_CATALOG_UNAVAILABLE });
-}
-
-function normalizeProvider(raw) {
-  if (!raw || typeof raw.id !== 'string' || raw.id.trim() === '') return null;
-  const id = raw.id.trim();
-  const adapterOwned = typeof raw.adapter_owned === 'boolean'
-    ? raw.adapter_owned
-    : typeof raw.adapterOwned === 'boolean' ? raw.adapterOwned : undefined;
-  return {
-    id,
-    name: typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : id,
-    ...(adapterOwned === undefined ? {} : { adapter_owned: adapterOwned }),
-  };
-}
-
-function normalizeModels(raw, provider) {
-  if (!Array.isArray(raw)) return [];
-  const seen = new Set();
-  const result = [];
-  for (const item of raw) {
-    if (!item || typeof item.id !== 'string' || item.id.trim() === '') continue;
-    const id = item.id.trim();
-    if (seen.has(id)) continue;
-    seen.add(id);
-    result.push({
-      id,
-      name: typeof item.name === 'string' && item.name.trim() ? item.name.trim() : id,
-      ...(typeof item.description === 'string' && item.description.trim() ? { description: item.description.trim() } : {}),
-      ...(Array.isArray(item.inputModalities) ? { inputModalities: item.inputModalities.filter((v) => v === 'text' || v === 'image') } : {}),
-    });
-  }
-  return result;
-}
-
-function safeDefault(getCurrentSelection) {
-  try {
-    const raw = typeof getCurrentSelection === 'function' ? getCurrentSelection() : undefined;
-    if (!raw || typeof raw.provider !== 'string' || typeof raw.model !== 'string') return null;
-    return {
-      provider: raw.provider,
-      model: raw.model,
-      ...(typeof raw.reasoningEffort === 'string' ? { reasoningEffort: raw.reasoningEffort } : {}),
-    };
-  } catch {
-    return null;
-  }
-}
-
-function healthHint(code, level, { provider, model, signal } = {}) {
-  return {
-    code,
-    level,
-    ...(typeof provider === 'string' && provider ? { provider } : {}),
-    ...(typeof model === 'string' && model ? { model } : {}),
-    ...(typeof signal === 'string' && signal ? { signal } : {}),
-  };
-}
-
-/**
- * Analyze only the effective, already-sanitized Harness catalog.
- *
- * This intentionally does not know an "expected" third-party catalog. A
- * narrow advertised list is therefore informational only: it can point a user
- * toward upstream/provider configuration, but it is never proof of a bad
- * override and never changes routing eligibility.
- */
-export function analyzeCatalogHealth({ providers = [], harnessDefault = null } = {}) {
-  const safeProviders = Array.isArray(providers) ? providers : [];
-  const hints = [];
-
-  if (safeProviders.length === 0) {
-    hints.push(healthHint(CATALOG_HEALTH_CODES.EMPTY_CATALOG, 'warning'));
-  }
-
-  for (const provider of safeProviders) {
-    const providerId = typeof provider?.id === 'string' ? provider.id : null;
-    const models = Array.isArray(provider?.models) ? provider.models : [];
-    if (provider?.error === 'MODEL_LIST_FAILED') {
-      hints.push(healthHint(CATALOG_HEALTH_CODES.PROVIDER_MODEL_LIST_FAILED, 'warning', { provider: providerId }));
-      continue;
-    }
-    if (models.length === 0) {
-      // Some providers intentionally accept exact model ids without advertising
-      // them. Keep this informational rather than turning it into a failure.
-      hints.push(healthHint(CATALOG_HEALTH_CODES.EMPTY_PROVIDER_MODELS, 'info', { provider: providerId }));
-    }
-  }
-
-  if (harnessDefault && typeof harnessDefault.provider === 'string' && typeof harnessDefault.model === 'string') {
-    const defaultProvider = safeProviders.find((provider) => provider?.id === harnessDefault.provider);
-    if (!defaultProvider) {
-      hints.push(healthHint(CATALOG_HEALTH_CODES.HARNESS_DEFAULT_PROVIDER_MISSING, 'warning', {
-        provider: harnessDefault.provider,
-        model: harnessDefault.model,
-      }));
-    } else if (defaultProvider.error !== 'MODEL_LIST_FAILED' && Array.isArray(defaultProvider.models) && defaultProvider.models.length > 0) {
-      const advertised = defaultProvider.models.some((model) => model?.id === harnessDefault.model);
-      if (!advertised) {
-        hints.push(healthHint(CATALOG_HEALTH_CODES.HARNESS_DEFAULT_MODEL_UNADVERTISED, 'info', {
-          provider: harnessDefault.provider,
-          model: harnessDefault.model,
-        }));
-      }
-    }
-  }
-
-  // A single provider advertising only one or two explicit models is a useful
-  // signal because local/provider overrides can produce this shape. It is only
-  // an INFO heuristic: legitimate providers can also have intentionally small
-  // catalogs, so Crew must not claim an override or route around it.
-  const healthyProviders = safeProviders.filter((provider) => provider?.error !== 'MODEL_LIST_FAILED');
-  const totalAdvertised = healthyProviders.reduce(
-    (sum, provider) => sum + (Array.isArray(provider?.models) ? provider.models.length : 0),
-    0,
-  );
-  if (healthyProviders.length === 1 && totalAdvertised > 0 && totalAdvertised <= 2) {
-    hints.push(healthHint(CATALOG_HEALTH_CODES.CATALOG_CONSTRAINED, 'info', {
-      provider: healthyProviders[0].id,
-      signal: 'single-provider-small-explicit-catalog',
-    }));
-  }
-
-  const warningCount = hints.filter((hint) => hint.level === 'warning').length;
-  const infoCount = hints.filter((hint) => hint.level === 'info').length;
-  return {
-    schema_version: 1,
-    warning_count: warningCount,
-    info_count: infoCount,
-    attention: warningCount > 0,
-    hints,
-  };
-}
-
-export async function readHarnessModelCatalog({ llm, getCurrentSelection, now = () => new Date().toISOString() } = {}) {
-  if (!llm || typeof llm.listProviders !== 'function' || typeof llm.listModels !== 'function') throw catalogError();
-  let rawProviders;
-  try {
-    rawProviders = llm.listProviders();
-  } catch {
-    throw catalogError();
-  }
-  if (!Array.isArray(rawProviders)) throw catalogError();
-  const providers = rawProviders.map(normalizeProvider).filter(Boolean);
-  let failed = 0;
-  const hydrated = await Promise.all(providers.map(async (provider) => {
-    try {
-      return { ...provider, models: normalizeModels(await llm.listModels(provider.id), provider.id) };
-    } catch {
-      failed += 1;
-      return { ...provider, models: [], error: 'MODEL_LIST_FAILED' };
-    }
-  }));
-  const harnessDefault = safeDefault(getCurrentSelection);
-  return {
-    providers: hydrated,
-    provider_count: hydrated.length,
-    model_count: hydrated.reduce((sum, provider) => sum + provider.models.length, 0),
-    harness_default: harnessDefault,
-    refreshed_at: now(),
-    partial: failed > 0,
-    health: analyzeCatalogHealth({ providers: hydrated, harnessDefault }),
-  };
-}
+// Read-only adapter from the DSH LLM registry to a credential-free Settings
+// payload. Provider/model discovery stays owned by Harness; Crew only reads
+// its registered routes and advertised catalog.
+
+export const MODEL_CATALOG_UNAVAILABLE = 'MODEL_CATALOG_UNAVAILABLE';
+
+export const CATALOG_HEALTH_CODES = Object.freeze({
+  EMPTY_CATALOG: 'EMPTY_CATALOG',
+  EMPTY_PROVIDER_MODELS: 'EMPTY_PROVIDER_MODELS',
+  PROVIDER_MODEL_LIST_FAILED: 'PROVIDER_MODEL_LIST_FAILED',
+  HARNESS_DEFAULT_PROVIDER_MISSING: 'HARNESS_DEFAULT_PROVIDER_MISSING',
+  HARNESS_DEFAULT_MODEL_UNADVERTISED: 'HARNESS_DEFAULT_MODEL_UNADVERTISED',
+  CATALOG_CONSTRAINED: 'CATALOG_CONSTRAINED',
+});
+
+function catalogError() {
+  return Object.assign(new Error('Unable to read Harness model catalog.'), { code: MODEL_CATALOG_UNAVAILABLE });
+}
+
+function normalizeProvider(raw) {
+  if (!raw || typeof raw.id !== 'string' || raw.id.trim() === '') return null;
+  const id = raw.id.trim();
+  const adapterOwned = typeof raw.adapter_owned === 'boolean'
+    ? raw.adapter_owned
+    : typeof raw.adapterOwned === 'boolean' ? raw.adapterOwned : undefined;
+  return {
+    id,
+    name: typeof raw.name === 'string' && raw.name.trim() ? raw.name.trim() : id,
+    ...(adapterOwned === undefined ? {} : { adapter_owned: adapterOwned }),
+  };
+}
+
+function normalizeModels(raw, provider) {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set();
+  const result = [];
+  for (const item of raw) {
+    if (!item || typeof item.id !== 'string' || item.id.trim() === '') continue;
+    const id = item.id.trim();
+    if (seen.has(id)) continue;
+    seen.add(id);
+    result.push({
+      id,
+      name: typeof item.name === 'string' && item.name.trim() ? item.name.trim() : id,
+      ...(typeof item.description === 'string' && item.description.trim() ? { description: item.description.trim() } : {}),
+      ...(Array.isArray(item.inputModalities) ? { inputModalities: item.inputModalities.filter((v) => v === 'text' || v === 'image') } : {}),
+    });
+  }
+  return result;
+}
+
+function safeDefault(getCurrentSelection) {
+  try {
+    const raw = typeof getCurrentSelection === 'function' ? getCurrentSelection() : undefined;
+    if (!raw || typeof raw.provider !== 'string' || typeof raw.model !== 'string') return null;
+    return {
+      provider: raw.provider,
+      model: raw.model,
+      ...(typeof raw.reasoningEffort === 'string' ? { reasoningEffort: raw.reasoningEffort } : {}),
+    };
+  } catch {
+    return null;
+  }
+}
+
+function healthHint(code, level, { provider, model, signal } = {}) {
+  return {
+    code,
+    level,
+    ...(typeof provider === 'string' && provider ? { provider } : {}),
+    ...(typeof model === 'string' && model ? { model } : {}),
+    ...(typeof signal === 'string' && signal ? { signal } : {}),
+  };
+}
+
+/**
+ * Analyze only the effective, already-sanitized Harness catalog.
+ *
+ * This intentionally does not know an "expected" third-party catalog. A
+ * narrow advertised list is therefore informational only: it can point a user
+ * toward upstream/provider configuration, but it is never proof of a bad
+ * override and never changes routing eligibility.
+ */
+export function analyzeCatalogHealth({ providers = [], harnessDefault = null } = {}) {
+  const safeProviders = Array.isArray(providers) ? providers : [];
+  const hints = [];
+
+  if (safeProviders.length === 0) {
+    hints.push(healthHint(CATALOG_HEALTH_CODES.EMPTY_CATALOG, 'warning'));
+  }
+
+  for (const provider of safeProviders) {
+    const providerId = typeof provider?.id === 'string' ? provider.id : null;
+    const models = Array.isArray(provider?.models) ? provider.models : [];
+    if (provider?.error === 'MODEL_LIST_FAILED') {
+      hints.push(healthHint(CATALOG_HEALTH_CODES.PROVIDER_MODEL_LIST_FAILED, 'warning', { provider: providerId }));
+      continue;
+    }
+    if (models.length === 0) {
+      // Some providers intentionally accept exact model ids without advertising
+      // them. Keep this informational rather than turning it into a failure.
+      hints.push(healthHint(CATALOG_HEALTH_CODES.EMPTY_PROVIDER_MODELS, 'info', { provider: providerId }));
+    }
+  }
+
+  if (harnessDefault && typeof harnessDefault.provider === 'string' && typeof harnessDefault.model === 'string') {
+    const defaultProvider = safeProviders.find((provider) => provider?.id === harnessDefault.provider);
+    if (!defaultProvider) {
+      hints.push(healthHint(CATALOG_HEALTH_CODES.HARNESS_DEFAULT_PROVIDER_MISSING, 'warning', {
+        provider: harnessDefault.provider,
+        model: harnessDefault.model,
+      }));
+    } else if (defaultProvider.error !== 'MODEL_LIST_FAILED' && Array.isArray(defaultProvider.models) && defaultProvider.models.length > 0) {
+      const advertised = defaultProvider.models.some((model) => model?.id === harnessDefault.model);
+      if (!advertised) {
+        hints.push(healthHint(CATALOG_HEALTH_CODES.HARNESS_DEFAULT_MODEL_UNADVERTISED, 'info', {
+          provider: harnessDefault.provider,
+          model: harnessDefault.model,
+        }));
+      }
+    }
+  }
+
+  // A single provider advertising only one or two explicit models is a useful
+  // signal because local/provider overrides can produce this shape. It is only
+  // an INFO heuristic: legitimate providers can also have intentionally small
+  // catalogs, so Crew must not claim an override or route around it.
+  const healthyProviders = safeProviders.filter((provider) => provider?.error !== 'MODEL_LIST_FAILED');
+  const totalAdvertised = healthyProviders.reduce(
+    (sum, provider) => sum + (Array.isArray(provider?.models) ? provider.models.length : 0),
+    0,
+  );
+  if (healthyProviders.length === 1 && totalAdvertised > 0 && totalAdvertised <= 2) {
+    hints.push(healthHint(CATALOG_HEALTH_CODES.CATALOG_CONSTRAINED, 'info', {
+      provider: healthyProviders[0].id,
+      signal: 'single-provider-small-explicit-catalog',
+    }));
+  }
+
+  const warningCount = hints.filter((hint) => hint.level === 'warning').length;
+  const infoCount = hints.filter((hint) => hint.level === 'info').length;
+  return {
+    schema_version: 1,
+    warning_count: warningCount,
+    info_count: infoCount,
+    attention: warningCount > 0,
+    hints,
+  };
+}
+
+export async function readHarnessModelCatalog({ llm, getCurrentSelection, now = () => new Date().toISOString() } = {}) {
+  if (!llm || typeof llm.listProviders !== 'function' || typeof llm.listModels !== 'function') throw catalogError();
+  let rawProviders;
+  try {
+    rawProviders = llm.listProviders();
+  } catch {
+    throw catalogError();
+  }
+  if (!Array.isArray(rawProviders)) throw catalogError();
+  const providers = rawProviders.map(normalizeProvider).filter(Boolean);
+  let failed = 0;
+  const hydrated = await Promise.all(providers.map(async (provider) => {
+    try {
+      return { ...provider, models: normalizeModels(await llm.listModels(provider.id), provider.id) };
+    } catch {
+      failed += 1;
+      return { ...provider, models: [], error: 'MODEL_LIST_FAILED' };
+    }
+  }));
+  const harnessDefault = safeDefault(getCurrentSelection);
+  return {
+    providers: hydrated,
+    provider_count: hydrated.length,
+    model_count: hydrated.reduce((sum, provider) => sum + provider.models.length, 0),
+    harness_default: harnessDefault,
+    refreshed_at: now(),
+    partial: failed > 0,
+    health: analyzeCatalogHealth({ providers: hydrated, harnessDefault }),
+  };
+}