create-walle 0.9.25 → 0.9.26

package/template/wall-e/llm/routing-policy.js

@@ -0,0 +1,796 @@
+'use strict';
+
+const providerRegistry = require('./registry');
+const { isCliBinaryAvailable, _internals: fallbackInternals } = require('./default-fallback');
+const { getProviderHealthStatus } = require('./provider-health-state');
+
+const POLICY_KEYS = {
+  mode: 'model_routing_policy_mode',
+  cliTail: 'model_routing_policy_cli_tail',
+  finalizationFallback: 'model_routing_policy_finalization_fallback',
+  lastRefreshAt: 'model_routing_policy_last_refresh_at',
+};
+
+const VALID_MODES = new Set(['smart', 'strict']);
+const LOCAL_PROVIDER_TYPES = new Set(['ollama', 'mlx', 'lmstudio']);
+const GATEWAY_ONLY_TYPES = new Set(['portkey_gateway']);
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeProviderType(value) {
+  const text = String(value || '').trim().toLowerCase().replace(/_/g, '-');
+  if (text === 'kimi' || text === 'kimi-k2' || text === 'moonshot-ai') return 'moonshot';
+  if (text === 'openai-compatible' || text.startsWith('openai-compatible-')) return 'openai';
+  return text;
+}
+
+function providerDisplayName(type) {
+  providerRegistry.ensureBootstrapped();
+  const entry = providerRegistry.get(normalizeProviderType(type));
+  if (entry?.manifest?.label) return entry.manifest.label;
+  return String(type || 'Provider')
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part) => part.length <= 3 ? part.toUpperCase() : part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ') || 'Provider';
+}
+
+function getKv(brain, key) {
+  try { return typeof brain?.getKv === 'function' ? brain.getKv(key) : ''; } catch { return ''; }
+}
+
+function setKv(brain, key, value) {
+  try {
+    if (typeof brain?.setKv === 'function') {
+      brain.setKv(key, value);
+      return true;
+    }
+  } catch {}
+  return false;
+}
+
+function kvBool(brain, key, fallback) {
+  const raw = getKv(brain, key);
+  if (raw === '') return fallback;
+  const text = String(raw).trim().toLowerCase();
+  if (['1', 'true', 'yes', 'on'].includes(text)) return true;
+  if (['0', 'false', 'no', 'off'].includes(text)) return false;
+  return fallback;
+}
+
+function getRoutingPolicySettings(brain) {
+  if (typeof brain?.ensureModelRoutingPolicy === 'function') {
+    try {
+      const row = brain.ensureModelRoutingPolicy('default');
+      if (row) {
+        return {
+          mode: row.mode || 'smart',
+          fallback_enabled: (row.mode || 'smart') !== 'strict',
+          cli_tail: row.cli_tail !== false,
+          finalization_fallback: row.finalization_fallback !== false,
+          last_refreshed_at: row.last_generated_at || null,
+          last_effective_at: row.last_effective_at || null,
+          last_error: row.last_error || null,
+          stale_reason: row.stale_reason || null,
+        };
+      }
+    } catch {}
+  }
+  const rawMode = String(getKv(brain, POLICY_KEYS.mode) || 'smart').trim().toLowerCase();
+  const mode = VALID_MODES.has(rawMode) ? rawMode : 'smart';
+  return {
+    mode,
+    fallback_enabled: mode !== 'strict',
+    cli_tail: kvBool(brain, POLICY_KEYS.cliTail, true),
+    finalization_fallback: kvBool(brain, POLICY_KEYS.finalizationFallback, true),
+    last_refreshed_at: getKv(brain, POLICY_KEYS.lastRefreshAt) || null,
+  };
+}
+
+function setRoutingPolicySettings(brain, input = {}) {
+  const current = getRoutingPolicySettings(brain);
+  const next = { ...current };
+  if (Object.prototype.hasOwnProperty.call(input, 'mode')) {
+    const mode = String(input.mode || '').trim().toLowerCase();
+    if (!VALID_MODES.has(mode)) throw new Error(`Invalid routing policy mode: ${input.mode}`);
+    next.mode = mode;
+    next.fallback_enabled = mode !== 'strict';
+  }
+  if (Object.prototype.hasOwnProperty.call(input, 'cli_tail')) next.cli_tail = input.cli_tail !== false;
+  if (Object.prototype.hasOwnProperty.call(input, 'cliTail')) next.cli_tail = input.cliTail !== false;
+  if (Object.prototype.hasOwnProperty.call(input, 'finalization_fallback')) next.finalization_fallback = input.finalization_fallback !== false;
+  if (Object.prototype.hasOwnProperty.call(input, 'finalizationFallback')) next.finalization_fallback = input.finalizationFallback !== false;
+
+  if (typeof brain?.updateModelRoutingPolicy === 'function') {
+    try {
+      const row = brain.updateModelRoutingPolicy('default', {
+        mode: next.mode,
+        cli_tail: next.cli_tail,
+        finalization_fallback: next.finalization_fallback,
+      });
+      return getRoutingPolicySettings({
+        ...brain,
+        ensureModelRoutingPolicy: () => row,
+      });
+    } catch {}
+  }
+  setKv(brain, POLICY_KEYS.mode, next.mode);
+  setKv(brain, POLICY_KEYS.cliTail, next.cli_tail ? '1' : '0');
+  setKv(brain, POLICY_KEYS.finalizationFallback, next.finalization_fallback ? '1' : '0');
+  return getRoutingPolicySettings(brain);
+}
+
+function modelMatchesProvider(model, type) {
+  try {
+    providerRegistry.ensureBootstrapped();
+    return providerRegistry.modelMatchesProvider(model, normalizeProviderType(type));
+  } catch {
+    return true;
+  }
+}
+
+function defaultModelForProvider(type) {
+  providerRegistry.ensureBootstrapped();
+  return providerRegistry.getDefaultModel(normalizeProviderType(type)) || providerRegistry.getDefaultModel('anthropic') || '';
+}
+
+function modelForProvider(brain, type, fallbackModel) {
+  const providerType = normalizeProviderType(type);
+  const specific = getKv(brain, `walle_model_${providerType}`);
+  if (specific && modelMatchesProvider(specific, providerType)) return specific;
+  if (fallbackModel && modelMatchesProvider(fallbackModel, providerType)) return fallbackModel;
+  const global = getKv(brain, 'walle_model');
+  if (global && modelMatchesProvider(global, providerType)) return global;
+  return defaultModelForProvider(providerType);
+}
+
+function providerRuntimeType(row = {}) {
+  const type = normalizeProviderType(row.type || row.provider_type);
+  if (type === 'anthropic' && row.auth_method === 'claude_cli') return 'claude-cli';
+  if (type === 'openai' && row.auth_method === 'codex_cli') return 'codex-cli';
+  return type;
+}
+
+function providerRuntimeAccess(row = {}, env = process.env) {
+  const type = normalizeProviderType(row.type || row.provider_type);
+  const authMethod = row.auth_method || 'api_key';
+  if (!row.enabled) return { ok: false, kind: 'disabled', reason: 'Provider is disabled.' };
+  if (LOCAL_PROVIDER_TYPES.has(type)) return { ok: true, kind: 'local', reason: 'Local runtime provider.' };
+  if (authMethod && authMethod !== 'api_key') return { ok: true, kind: authMethod, reason: 'Configured provider auth method.' };
+  if (row.api_key_encrypted) return { ok: true, kind: 'stored_credential', reason: 'Stored provider credential.' };
+  if (fallbackInternals._hasEnvKey(type, env)) return { ok: true, kind: 'environment', reason: 'Credential available from environment.' };
+  return { ok: false, kind: 'missing_credential', reason: 'No stored credential or environment key.' };
+}
+
+function publicRuntimeHealth(id, type, model, health, brain) {
+  const runtime = id && health?.getProviderHealth ? health.getProviderHealth(id) : null;
+  const persisted = getProviderHealthStatus(type, model, { brain });
+  const runtimeHasEvidence = runtime && Number(runtime.totalCalls || 0) > 0;
+  const status = runtimeHasEvidence ? runtime.status : (persisted ? persisted.status : 'unknown');
+  return {
+    status,
+    consecutive_failures: runtimeHasEvidence ? (runtime?.consecutiveFailures || 0) : 0,
+    last_error: runtime?.lastError?.message || persisted?.error || '',
+    last_success_at: runtimeHasEvidence && runtime?.lastSuccess ? runtime.lastSuccess.toISOString?.() || String(runtime.lastSuccess) : null,
+    persisted_status: persisted || null,
+  };
+}
+
+function loadProviderRows(brain) {
+  const rows = [];
+  try {
+    for (const row of brain?.listModelProviders?.() || []) {
+      if (!row || GATEWAY_ONLY_TYPES.has(normalizeProviderType(row.type))) continue;
+      try {
+        rows.push(brain.getModelProviderWithKey?.(row.id) || row);
+      } catch {
+        rows.push(row);
+      }
+    }
+  } catch {}
+  return rows;
+}
+
+function firstEnabledModelForProvider(brain, providerId) {
+  try {
+    const model = (brain?.listModelsByProvider?.(providerId) || []).find((item) => item && item.enabled !== 0);
+    return model?.model_id || model?.modelId || '';
+  } catch {
+    return '';
+  }
+}
+
+function rowCandidate(row, context) {
+  const type = normalizeProviderType(row.type);
+  const runtimeType = providerRuntimeType(row);
+  const access = providerRuntimeAccess(row, context.env);
+  const firstModel = firstEnabledModelForProvider(context.brain, row.id);
+  const model = runtimeType.endsWith('-cli')
+    ? defaultModelForProvider(runtimeType)
+    : modelForProvider(context.brain, type, firstModel);
+  const health = publicRuntimeHealth(row.id, runtimeType, model, context.health, context.brain);
+  const isDown = health.status === 'down' || health.status === 'error';
+  const routePolicy = typeof context.brain?.getProviderRoutePolicy === 'function'
+    ? context.brain.getProviderRoutePolicy(type)
+    : 'auto';
+  const included = access.ok && !isDown;
+  return {
+    id: row.id || `${type}-default`,
+    provider_id: row.id || null,
+    provider_type: type,
+    runtime_type: runtimeType,
+    provider_name: row.name || providerDisplayName(type),
+    label: row.name || providerDisplayName(type),
+    model,
+    source: 'provider-card',
+    connection_kind: row.auth_method && row.auth_method !== 'api_key' ? row.auth_method : 'direct',
+    route_policy: routePolicy,
+    runtime_access: access.kind,
+    included,
+    excluded_reason: included ? '' : (isDown ? 'Provider is marked down by runtime health.' : access.reason),
+    health,
+    updated_at: row.updated_at || '',
+  };
+}
+
+function envCandidate(type, context) {
+  const providerType = normalizeProviderType(type);
+  if (!fallbackInternals._hasEnvKey(providerType, context.env)) return null;
+  const model = modelForProvider(context.brain, providerType, '');
+  const id = `${providerType}-env`;
+  return {
+    id,
+    provider_id: null,
+    provider_type: providerType,
+    runtime_type: providerType,
+    provider_name: providerDisplayName(providerType),
+    label: `${providerDisplayName(providerType)} env`,
+    model,
+    source: 'environment',
+    connection_kind: 'environment',
+    route_policy: 'auto',
+    runtime_access: 'environment',
+    included: true,
+    excluded_reason: '',
+    health: publicRuntimeHealth(id, providerType, model, context.health, context.brain),
+    updated_at: '',
+  };
+}
+
+function cliCandidate(id, bin, context) {
+  const available = context.settings.cli_tail && context.isCliAvailable(bin);
+  const model = defaultModelForProvider(id);
+  return {
+    id,
+    provider_id: null,
+    provider_type: id,
+    runtime_type: id,
+    provider_name: providerDisplayName(id),
+    label: providerDisplayName(id),
+    model,
+    source: 'cli-tail',
+    connection_kind: 'cli',
+    route_policy: 'auto',
+    runtime_access: available ? 'cli' : 'missing_cli',
+    included: available,
+    excluded_reason: available ? '' : `${bin} CLI not found or CLI fallback is disabled.`,
+    health: publicRuntimeHealth(id, id, model, context.health, context.brain),
+    updated_at: '',
+  };
+}
+
+function providerTypeOrderScore(candidate, defaultType) {
+  if (candidate.provider_type === defaultType || candidate.runtime_type === defaultType) return -1000;
+  if (!candidate.included) return 1000;
+  if (candidate.health?.status === 'healthy') return 0;
+  if (candidate.health?.status === 'degraded') return 10;
+  if (candidate.source === 'provider-card') return 20;
+  if (candidate.source === 'environment') return 30;
+  if (candidate.source === 'cli-tail') return 70;
+  return 50;
+}
+
+function dedupeProviderCandidates(candidates, brain) {
+  const byType = new Map();
+  const preferredByType = new Map();
+  for (const row of loadProviderRows(brain)) {
+    const type = normalizeProviderType(row.type);
+    if (!preferredByType.has(type)) {
+      try { preferredByType.set(type, brain.getPreferredModelProviderForType?.(type)?.id || ''); } catch {}
+    }
+  }
+  for (const candidate of candidates) {
+    if (candidate.source !== 'provider-card') {
+      byType.set(candidate.id, candidate);
+      continue;
+    }
+    const key = candidate.provider_type;
+    const existing = byType.get(key);
+    if (!existing) {
+      byType.set(key, candidate);
+      continue;
+    }
+    const preferredId = preferredByType.get(key);
+    if (preferredId && candidate.provider_id === preferredId) {
+      byType.set(key, candidate);
+      continue;
+    }
+    if (candidate.included && !existing.included) {
+      byType.set(key, candidate);
+      continue;
+    }
+    if (candidate.included === existing.included && String(candidate.updated_at || '') > String(existing.updated_at || '')) {
+      byType.set(key, candidate);
+    }
+  }
+  return Array.from(byType.values());
+}
+
+function orderCandidates(candidates, defaultType) {
+  return candidates.slice().sort((a, b) => {
+    const ar = providerTypeOrderScore(a, defaultType);
+    const br = providerTypeOrderScore(b, defaultType);
+    if (ar !== br) return ar - br;
+    if (String(b.updated_at || '') !== String(a.updated_at || '')) return String(b.updated_at || '').localeCompare(String(a.updated_at || ''));
+    return String(a.label || a.id).localeCompare(String(b.label || b.id));
+  });
+}
+
+function primaryFromCandidates(candidates, defaultType) {
+  if (defaultType) {
+    const exact = candidates.find((candidate) => candidate.included && (
+      candidate.provider_type === defaultType || candidate.runtime_type === defaultType
+    ));
+    if (exact) return exact;
+  }
+  return candidates.find((candidate) => candidate.included && candidate.source !== 'cli-tail')
+    || candidates.find((candidate) => candidate.included)
+    || null;
+}
+
+function applyDefaultRepair(brain, policy) {
+  const actions = [];
+  const currentType = policy.default?.configured_provider_type || '';
+  const primary = policy.default?.candidate || null;
+  if (!primary || primary.source === 'cli-tail') return actions;
+  const needsProvider = !currentType || policy.default.status === 'unusable';
+  const needsModel = primary.model && !getKv(brain, 'walle_model');
+  if (!needsProvider && !needsModel) return actions;
+  try {
+    if (typeof brain.setDefaultProviderSelection === 'function') {
+      brain.setDefaultProviderSelection({
+        type: primary.provider_type,
+        requestedModel: primary.model,
+        targetModel: primary.model,
+      });
+    } else {
+      setKv(brain, 'walle_provider', primary.provider_type);
+      if (primary.model) setKv(brain, 'walle_model', primary.model);
+    }
+    actions.push({
+      type: needsProvider ? 'default_provider_selected' : 'default_model_selected',
+      provider_type: primary.provider_type,
+      model: primary.model,
+    });
+  } catch (err) {
+    actions.push({ type: 'default_repair_failed', error: err.message || String(err) });
+  }
+  return actions;
+}
+
+function buildRoutingPolicy(options = {}) {
+  providerRegistry.ensureBootstrapped();
+  const brain = options.brain;
+  const env = options.env || process.env;
+  const health = options.health || safeDefaultHealth();
+  const settings = getRoutingPolicySettings(brain);
+  const context = {
+    brain,
+    env,
+    health,
+    settings,
+    isCliAvailable: options.isCliAvailable || isCliBinaryAvailable,
+  };
+  const rawDefault = normalizeProviderType(getKv(brain, 'walle_provider') || env.WALLE_PROVIDER || '');
+  const rawDefaultSource = getKv(brain, 'walle_provider') ? 'provider-card' : (env.WALLE_PROVIDER ? 'environment' : 'auto');
+  const rowCandidates = dedupeProviderCandidates(loadProviderRows(brain).map((row) => rowCandidate(row, context)), brain);
+  const rowTypes = new Set(rowCandidates.map((candidate) => candidate.provider_type));
+  const envCandidates = providerRegistry.ids()
+    .filter((id) => !rowTypes.has(normalizeProviderType(id)) && !String(id).endsWith('-cli'))
+    .map((id) => envCandidate(id, context))
+    .filter(Boolean);
+  const cliCandidates = [
+    cliCandidate('claude-cli', 'claude', context),
+    cliCandidate('codex-cli', 'codex', context),
+  ];
+  let candidates = rowCandidates.concat(envCandidates, cliCandidates);
+  if (settings.mode === 'strict' && rawDefault) {
+    candidates = candidates.map((candidate) => {
+      const isDefault = rawDefault && (candidate.provider_type === rawDefault || candidate.runtime_type === rawDefault);
+      if (isDefault) return candidate;
+      return { ...candidate, included: false, excluded_reason: 'Strict mode only uses the provider-card default.' };
+    });
+  }
+  let ordered = orderCandidates(candidates, rawDefault);
+  const primary = primaryFromCandidates(ordered, rawDefault);
+  if (settings.mode === 'strict' && !rawDefault && primary) {
+    ordered = ordered.map((candidate) => {
+      if (candidate.id === primary.id) return candidate;
+      return { ...candidate, included: false, excluded_reason: 'Strict mode will use the initialized provider-card default.' };
+    });
+  }
+  let chain = ordered.filter((candidate) => candidate.included);
+  if (primary) {
+    chain = [primary].concat(chain.filter((candidate) => candidate.id !== primary.id));
+  }
+  chain = chain.map((candidate, index) => ({
+    ...candidate,
+    order: index + 1,
+    role: index === 0 ? 'primary' : 'fallback',
+  }));
+  const defaultCandidate = rawDefault
+    ? ordered.find((candidate) => candidate.provider_type === rawDefault || candidate.runtime_type === rawDefault) || null
+    : primary;
+  const policy = {
+    generated_at: nowIso(),
+    settings,
+    trigger_classes: Array.from(fallbackInternals.FALLTHROUGH_CLASSES || []),
+    default: {
+      configured_provider_type: rawDefault || null,
+      source: rawDefaultSource,
+      status: rawDefault
+        ? (defaultCandidate?.included ? 'usable' : 'unusable')
+        : (primary ? 'auto-selected' : 'missing'),
+      provider_type: (defaultCandidate || primary)?.provider_type || null,
+      runtime_type: (defaultCandidate || primary)?.runtime_type || null,
+      provider_name: (defaultCandidate || primary)?.provider_name || null,
+      model: (defaultCandidate || primary)?.model || null,
+      reason: defaultCandidate?.included
+        ? 'Provider-card default is usable.'
+        : (defaultCandidate?.excluded_reason || (primary ? 'No explicit default; using best available provider.' : 'No usable provider found.')),
+      candidate: defaultCandidate || primary || null,
+    },
+    chain,
+    candidates: ordered,
+    excluded: ordered.filter((candidate) => !candidate.included),
+    recommendations: [],
+    actions: [],
+  };
+  if (!rawDefault && primary && primary.source !== 'cli-tail') {
+    policy.recommendations.push({
+      type: 'select_default_provider',
+      provider_type: primary.provider_type,
+      model: primary.model,
+      message: 'No provider-card default is set. CTM can initialize it from the best available provider.',
+    });
+  } else if (rawDefault && defaultCandidate && !defaultCandidate.included && primary && primary.provider_type !== rawDefault) {
+    policy.recommendations.push({
+      type: 'repair_unusable_default',
+      provider_type: primary.provider_type,
+      model: primary.model,
+      message: 'The current default is not usable. Refresh can move the default to the best available provider.',
+    });
+  }
+
+  if (options.repairDefault) {
+    policy.actions = applyDefaultRepair(brain, policy);
+    const refreshStamp = nowIso();
+    setKv(brain, POLICY_KEYS.lastRefreshAt, refreshStamp);
+    if (typeof brain.updateModelRoutingPolicy === 'function') {
+      try {
+        brain.updateModelRoutingPolicy('default', { last_generated_at: refreshStamp });
+      } catch {}
+    }
+    if (policy.actions.some((action) => !/failed$/.test(action.type))) {
+      const recomputed = buildRoutingPolicy({ ...options, repairDefault: false });
+      recomputed.actions = policy.actions;
+      return recomputed;
+    }
+    policy.settings = getRoutingPolicySettings(brain);
+  }
+  return policy;
+}
+
+function _routeKey(route = {}) {
+  return [
+    route.provider_id || '',
+    route.runtime_type || route.provider_type || '',
+    route.provider_type || '',
+    route.model || route.model_id || '',
+  ].join('|');
+}
+
+function _mergeEffectiveRoutes(generatedRoutes = [], userRoutes = []) {
+  const generated = Array.isArray(generatedRoutes) ? generatedRoutes : [];
+  const manualAll = (Array.isArray(userRoutes) ? userRoutes : []).filter(Boolean);
+  const out = [];
+  const seen = new Set();
+  const primary = generated.find((route) => route && route.role === 'primary') || generated[0] || null;
+  const primaryKey = primary ? _routeKey(primary) : '';
+  const disabledKeys = new Set(manualAll
+    .filter((route) => route.enabled === false && _routeKey(route) !== primaryKey)
+    .map(_routeKey)
+    .filter(Boolean));
+  const manual = manualAll.filter((route) => route.enabled !== false);
+  function add(route, role) {
+    if (!route) return;
+    const key = _routeKey(route);
+    if (seen.has(key) || (disabledKeys.has(key) && key !== primaryKey)) return;
+    seen.add(key);
+    out.push({
+      ...route,
+      role: role || route.role || (out.length === 0 ? 'primary' : 'fallback'),
+      order: out.length + 1,
+    });
+  }
+  if (primary) add(primary, 'primary');
+  for (const route of manual) add(route, out.length === 0 ? 'primary' : 'fallback');
+  for (const route of generated) add(route, out.length === 0 ? 'primary' : 'fallback');
+  return out.map((route, index) => ({
+    ...route,
+    order: index + 1,
+    role: index === 0 ? 'primary' : 'fallback',
+  }));
+}
+
+function _persistedSettings(policyRow = {}) {
+  const mode = VALID_MODES.has(policyRow.mode) ? policyRow.mode : 'smart';
+  return {
+    mode,
+    fallback_enabled: mode !== 'strict',
+    cli_tail: policyRow.cli_tail !== false,
+    finalization_fallback: policyRow.finalization_fallback !== false,
+    last_refreshed_at: policyRow.last_generated_at || null,
+    last_effective_at: policyRow.last_effective_at || null,
+    last_error: policyRow.last_error || null,
+    stale_reason: policyRow.stale_reason || null,
+  };
+}
+
+function _defaultFromPersisted(brain, chain = [], settings = {}) {
+  const primary = chain[0] || null;
+  const configuredType = normalizeProviderType(getKv(brain, 'walle_provider') || process.env.WALLE_PROVIDER || '');
+  if (primary) {
+    const matchesDefault = configuredType && (
+      primary.provider_type === configuredType || primary.runtime_type === configuredType
+    );
+    return {
+      configured_provider_type: configuredType || null,
+      source: getKv(brain, 'walle_provider') ? 'provider-card' : (process.env.WALLE_PROVIDER ? 'environment' : 'auto'),
+      status: configuredType ? (matchesDefault ? 'usable' : 'fallback-ready') : 'auto-selected',
+      provider_type: primary.provider_type || null,
+      runtime_type: primary.runtime_type || primary.provider_type || null,
+      provider_name: primary.provider_name || primary.label || providerDisplayName(primary.provider_type),
+      model: primary.model || primary.model_id || null,
+      reason: matchesDefault
+        ? 'Provider-card default is usable.'
+        : (settings.mode === 'strict'
+          ? 'Strict mode uses the persisted default route.'
+          : 'Persisted effective route is ready.'),
+      candidate: primary,
+    };
+  }
+  return {
+    configured_provider_type: configuredType || null,
+    source: configuredType ? 'provider-card' : 'auto',
+    status: 'missing',
+    provider_type: null,
+    runtime_type: null,
+    provider_name: null,
+    model: null,
+    reason: settings.last_error || 'No usable provider route has been materialized yet.',
+    candidate: null,
+  };
+}
+
+function _publicPolicyFromPersisted(brain, snapshot = {}, extras = {}) {
+  const policyRow = snapshot.policy || {};
+  const routes = snapshot.routes || {};
+  const settings = _persistedSettings(policyRow);
+  const effective = Array.isArray(routes.effective) ? routes.effective : [];
+  const generated = Array.isArray(routes.generated) ? routes.generated : [];
+  const user = Array.isArray(routes.user) ? routes.user : [];
+  const chainSource = effective.length ? 'effective' : (generated.length ? 'generated' : 'empty');
+  const chain = (effective.length ? effective : generated).map((route, index) => ({
+    ...route,
+    route_key: _routeKey(route),
+    order: index + 1,
+    role: index === 0 ? 'primary' : 'fallback',
+  }));
+  const publicUserRoutes = user.map((route, index) => ({
+    ...route,
+    route_key: _routeKey(route),
+    order: index + 1,
+    role: route.role || 'fallback',
+  }));
+  const publicGeneratedRoutes = generated.map((route, index) => ({
+    ...route,
+    route_key: _routeKey(route),
+    order: index + 1,
+    role: index === 0 ? 'primary' : 'fallback',
+  }));
+  return {
+    generated_at: policyRow.last_generated_at || null,
+    persisted: true,
+    policy_id: policyRow.id || 'default',
+    chain_source: chainSource,
+    settings,
+    trigger_classes: Array.from(fallbackInternals.FALLTHROUGH_CLASSES || []),
+    default: _defaultFromPersisted(brain, chain, settings),
+    chain,
+    candidates: chain,
+    excluded: [],
+    recommendations: extras.recommendations || [],
+    actions: extras.actions || [],
+    sources: {
+      user_count: user.length,
+      generated_count: generated.length,
+      effective_count: effective.length,
+    },
+    user_routes: publicUserRoutes,
+    generated_routes: publicGeneratedRoutes,
+  };
+}
+
+function getPersistedRoutingPolicy(options = {}) {
+  const brain = options.brain;
+  if (!brain || typeof brain.getModelRoutingPolicy !== 'function') {
+    return buildRoutingPolicy(options);
+  }
+  const snapshot = brain.getModelRoutingPolicy('default');
+  const hasEffective = Array.isArray(snapshot.routes?.effective) && snapshot.routes.effective.length > 0;
+  const hasGenerated = Array.isArray(snapshot.routes?.generated) && snapshot.routes.generated.length > 0;
+  if (!hasEffective && !hasGenerated && options.generateIfMissing !== false) {
+    return materializeRoutingPolicy(options);
+  }
+  return _publicPolicyFromPersisted(brain, snapshot);
+}
+
+function materializeRoutingPolicy(options = {}) {
+  const brain = options.brain;
+  const computed = buildRoutingPolicy(options);
+  if (!brain || typeof brain.replaceModelRoutingPolicyRoutes !== 'function') return computed;
+  try {
+    const userRoutes = typeof brain.listModelRoutingPolicyRoutes === 'function'
+      ? brain.listModelRoutingPolicyRoutes('default', 'user')
+      : [];
+    const generatedRoutes = Array.isArray(computed.chain) ? computed.chain : [];
+    const effectiveRoutes = _mergeEffectiveRoutes(generatedRoutes, userRoutes);
+    brain.replaceModelRoutingPolicyRoutes('default', 'generated', generatedRoutes);
+    brain.replaceModelRoutingPolicyRoutes('default', 'effective', effectiveRoutes);
+    const stamp = computed.generated_at || nowIso();
+    if (typeof brain.updateModelRoutingPolicy === 'function') {
+      brain.updateModelRoutingPolicy('default', {
+        mode: computed.settings?.mode || 'smart',
+        cli_tail: computed.settings?.cli_tail !== false,
+        finalization_fallback: computed.settings?.finalization_fallback !== false,
+        last_generated_at: stamp,
+        last_effective_at: nowIso(),
+        last_error: null,
+        stale_reason: null,
+      });
+    } else {
+      setKv(brain, POLICY_KEYS.lastRefreshAt, stamp);
+    }
+    const persisted = getPersistedRoutingPolicy({ ...options, generateIfMissing: false });
+    persisted.actions = computed.actions || [];
+    persisted.recommendations = computed.recommendations || [];
+    persisted.excluded = computed.excluded || [];
+    persisted.candidates = computed.candidates || persisted.chain;
+    return persisted;
+  } catch (err) {
+    try {
+      if (typeof brain.updateModelRoutingPolicy === 'function') {
+        brain.updateModelRoutingPolicy('default', {
+          last_error: err.message || String(err),
+          stale_reason: 'materialization_failed',
+        });
+      }
+    } catch {}
+    throw err;
+  }
+}
+
+function _indexedRoutes(routes = []) {
+  const map = new Map();
+  for (const route of Array.isArray(routes) ? routes : []) {
+    if (!route) continue;
+    const key = route.route_key || _routeKey(route);
+    if (key && !map.has(key)) map.set(key, route);
+  }
+  return map;
+}
+
+function _routeInputKey(route = {}) {
+  return route.route_key || route.key || _routeKey(route);
+}
+
+function setUserRoutingPolicyRoutes(options = {}) {
+  const brain = options.brain;
+  if (!brain || typeof brain.replaceModelRoutingPolicyRoutes !== 'function') {
+    throw new Error('Wall-E brain does not support routing policy route edits');
+  }
+  const requestedRoutes = Array.isArray(options.routes) ? options.routes : [];
+  let snapshot = typeof brain.getModelRoutingPolicy === 'function'
+    ? brain.getModelRoutingPolicy('default')
+    : { routes: {} };
+  if (!Array.isArray(snapshot.routes?.generated) || snapshot.routes.generated.length === 0) {
+    materializeRoutingPolicy({ ...options, repairDefault: false });
+    snapshot = brain.getModelRoutingPolicy('default');
+  }
+  const generatedRoutes = Array.isArray(snapshot.routes?.generated) ? snapshot.routes.generated : [];
+  const effectiveRoutes = Array.isArray(snapshot.routes?.effective) && snapshot.routes.effective.length
+    ? snapshot.routes.effective
+    : generatedRoutes;
+  const userRoutes = Array.isArray(snapshot.routes?.user) ? snapshot.routes.user : [];
+  const candidatesByKey = _indexedRoutes([].concat(effectiveRoutes, generatedRoutes, userRoutes));
+  const primary = generatedRoutes.find((route) => route && route.role === 'primary') || generatedRoutes[0] || effectiveRoutes[0] || null;
+  const primaryKey = primary ? _routeKey(primary) : '';
+  const manualRoutes = [];
+  const seen = new Set();
+
+  for (const requested of requestedRoutes) {
+    if (!requested) continue;
+    const key = _routeInputKey(requested);
+    if (!key || key === primaryKey || seen.has(key)) continue;
+    const base = candidatesByKey.get(key);
+    if (!base) throw new Error(`Unknown fallback route: ${key}`);
+    const providerType = base.provider_type || base.providerType || base.type;
+    if (!providerType) continue;
+    const enabled = requested.enabled !== false && requested.enabled !== 0;
+    manualRoutes.push({
+      ...base,
+      route_key: key,
+      order: manualRoutes.length + 1,
+      role: 'fallback',
+      enabled,
+      reason: enabled
+        ? (requested.reason || base.reason || '')
+        : (requested.reason || 'Disabled by user'),
+      metadata: {
+        ...(base.metadata && typeof base.metadata === 'object' ? base.metadata : {}),
+        manual_route: true,
+      },
+    });
+    seen.add(key);
+  }
+
+  brain.replaceModelRoutingPolicyRoutes('default', 'user', manualRoutes);
+  const storedUserRoutes = typeof brain.listModelRoutingPolicyRoutes === 'function'
+    ? brain.listModelRoutingPolicyRoutes('default', 'user')
+    : manualRoutes;
+  const effectiveRoutesNext = _mergeEffectiveRoutes(generatedRoutes, storedUserRoutes);
+  brain.replaceModelRoutingPolicyRoutes('default', 'effective', effectiveRoutesNext);
+  if (typeof brain.updateModelRoutingPolicy === 'function') {
+    brain.updateModelRoutingPolicy('default', {
+      last_effective_at: nowIso(),
+      last_error: null,
+      stale_reason: null,
+    });
+  }
+  return getPersistedRoutingPolicy({ ...options, generateIfMissing: false });
+}
+
+function safeDefaultHealth() {
+  try { return require('./health').default; } catch { return null; }
+}
+
+module.exports = {
+  buildRoutingPolicy,
+  getPersistedRoutingPolicy,
+  materializeRoutingPolicy,
+  getRoutingPolicySettings,
+  setRoutingPolicySettings,
+  setUserRoutingPolicyRoutes,
+  _internals: {
+    POLICY_KEYS,
+    normalizeProviderType,
+    providerRuntimeAccess,
+    providerRuntimeType,
+    defaultModelForProvider,
+    _mergeEffectiveRoutes,
+    _routeKey,
+  },
+};