@qadanm/opencode-smart-router 0.0.0-stage → 0.6.1

package/src/core/config.ts

@@ -0,0 +1,1047 @@
+import { existsSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import {
+  DEFAULT_OFFLINE_SETTINGS,
+  MINIMUM_OFFLINE_CONTEXT,
+  isLoopbackURL,
+  type OfflineSettings,
+} from "./offline/mode.js"
+import { join } from "node:path"
+import type {
+  CostTier,
+  ModelDefinition,
+  ModelSettings,
+  PremiumSettings,
+  PrivacySettings,
+  ProviderSettings,
+  RouterSettings,
+} from "./types.js"
+
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json }
+
+export interface SettingsLoadResult {
+  settings: RouterSettings
+  warnings: string[]
+  sources: string[]
+  /**
+   * Provider ids whose `enabled` the user set explicitly, in plugin options or
+   * in a config file.
+   *
+   * Credential detection fills in the providers a user never mentioned, but it
+   * must never overrule one they did. Without this set, "I turned OpenDesign
+   * off" and "I never configured OpenDesign" are indistinguishable after the
+   * merge, and detection would silently switch a deliberate choice back on.
+   */
+  explicitProviderEnable: ReadonlySet<string>
+}
+
+/**
+ * Provider ids with an explicit boolean `enabled` in a config document. Reads
+ * the raw input rather than the merged settings, because the merge has already
+ * lost the distinction between "set to true" and "defaulted to true".
+ */
+const explicitProviderEnable = (input: unknown): Set<string> => {
+  const found = new Set<string>()
+  if (!isRecord(input)) return found
+  const providers = input.providers
+  if (!isRecord(providers)) return found
+  for (const [id, value] of Object.entries(providers)) {
+    if (isRecord(value) && typeof value.enabled === "boolean") found.add(id)
+  }
+  return found
+}
+
+const providerDefaults = (plan: string, extra: Partial<ProviderSettings> = {}): ProviderSettings => ({
+  enabled: true,
+  plan,
+  reserveMonthlyPct: 10,
+  reserveWeeklyPct: 15,
+  reserveFiveHourPct: 10,
+  allowExtraUsage: false,
+  probeUsage: true,
+  ...extra,
+})
+
+export const DEFAULT_SETTINGS: RouterSettings = {
+  enabled: true,
+  mode: "balanced",
+  dryRun: false,
+  providers: {
+    // OpenCode Go: per-model monthly allowances. The plan catalog holds the
+    // per-model table; the provider settings only carry policy.
+    "opencode-go": providerDefaults("go"),
+    commandcode: providerDefaults("goat", {
+      probeUsage: true,
+      monthlyCreditsUsd: 70,
+      fiveHourCapUsd: 14,
+      weeklyCapUsd: 35,
+    }),
+    // OpenDesign is optional and disabled by default. A user without
+    // OpenDesign credentials sees no behavior change at all.
+    //
+    // Pro is the default assumed tier because it is the only tier with a
+    // separate plan-model pool; the catalog is authoritative for the numbers
+    // and the live gateway is authoritative for entitlement.
+    // Ollama is a local provider. It is enabled so offline mode can reach it,
+    // and its models stay unapproved so online routing never picks them. The
+    // provider being enabled is not the same as its models being approved.
+    ollama: providerDefaults("local", { probeUsage: false, allowExtraUsage: false }),
+    opendesign: providerDefaults("pro", {
+      enabled: false,
+      probeUsage: true,
+      reserveMonthlyPct: 5,
+      reserveWeeklyPct: 10,
+      reserveFiveHourPct: 0,
+      allowExtraUsage: false,
+      subscriptionOnly: true,
+      providerScopedQuota: true,
+      // Pro has no five-hour Design Plan window.
+      ignoreFiveHourWindow: true,
+    }),
+  },
+  privacy: {
+    allowTrainingModels: false,
+    allowFreeModels: false,
+    requireZdr: false,
+  },
+  premium: {
+    mode: "auto",
+    monthlyBudgetUsd: 120,
+    oneShotApproval: true,
+  },
+  routing: {
+    intelligenceFloor: 39.5,
+    designFloor: 60,
+    sophisticatedDesignFloor: 75,
+    switchHysteresisPct: 20,
+    largeContextTokens: 300_000,
+    largeContextHysteresisPct: 35,
+    maxEscalationsPerTask: 2,
+    preferSameProvider: true,
+    // A defect in this plugin must never make the editor unusable. Routing is
+    // an optimization; the host works without it. Failing open means an
+    // internal error leaves the current model in place and lets the prompt
+    // through. An owner who would rather be stopped than pay for an unrouted
+    // request can set this to true explicitly.
+    failClosed: false,
+    protectEscalationPool: true,
+    longContextFloorTokens: 1_000_000,
+    calibrateFloor: false,
+  },
+  quota: {
+    probeOpenCodeGo: true,
+    probeCommandCode: true,
+    probeOpenDesign: true,
+    probeIntervalMinutes: 5,
+    bootstrapSessions: 100,
+    bootstrapDays: 31,
+  },
+  contextHealth: {
+    enabled: true,
+    warnAtTokens: 400_000,
+    recommendAtTokens: 700_000,
+  },
+  // Preserve full context by default. Compaction is a destructive operation
+  // that only ever existed to survive a small allowance.
+  contextManagement: {
+    mode: "native",
+    enabled: true,
+    compactAtTokens: 0,
+    cooldownMinutes: 10,
+    allowEmergencyCompaction: true,
+  },
+  speed: {
+    enabled: true,
+    weightPct: 15,
+    minSamples: 3,
+    slowRouteMultiple: 2.5,
+  },
+  ui: {
+    // Off by default. A plugin that renames a stranger's chats on install is a
+    // bug, not a feature: the session title is the user's, and status belongs in
+    // the desktop panel or the terminal's status line. Turning this on is an
+    // explicit choice, and turning it back off restores the original names.
+    notifications: true,
+    compactMode: false,
+    compact: false,
+  },
+  logging: {
+    storePromptText: false,
+    decisionLogSize: 100,
+    diagnostics: true,
+  },
+  models: {
+    approved: [],
+    excluded: [],
+    tierOverrides: {},
+    definitions: [],
+  },
+  // Offline mode is off unless explicitly enabled. It lives here so that a
+  // caller reading DEFAULT_SETTINGS can see the full shape without having to
+  // know that offline is optional.
+  offline: DEFAULT_OFFLINE_SETTINGS,
+}
+
+const numberOr = (value: unknown): number | undefined => {
+  if (typeof value === "number" && Number.isFinite(value)) return value
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return undefined
+}
+
+const timeValue = (value: unknown): number | undefined => {
+  if (typeof value === "number" && Number.isFinite(value)) return value
+  if (typeof value === "string") {
+    const parsed = Date.parse(value)
+    if (Number.isFinite(parsed)) return parsed
+  }
+  return undefined
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const asBoolean = (value: unknown, fallback: boolean, warnings: string[], path: string): boolean => {
+  // Absent and invalid are different. A key that was never written takes the
+  // fallback silently; only a value the user actually provided can be wrong.
+  // Collapsing the two produced dozens of warnings for a config that set one
+  // provider plan, which buried the real problems in the noise.
+  if (value === undefined) return fallback
+  if (typeof value === "boolean") return value
+  warnings.push(`${path} must be a boolean; using ${fallback}`)
+  return fallback
+}
+
+const asNumber = (
+  value: unknown,
+  fallback: number,
+  warnings: string[],
+  path: string,
+  min: number,
+  max: number,
+): number => {
+  if (value === undefined) return fallback
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    warnings.push(`${path} must be a finite number; using ${fallback}`)
+    return fallback
+  }
+  const clamped = Math.min(max, Math.max(min, value))
+  if (clamped !== value) warnings.push(`${path} was clamped to ${clamped}`)
+  return clamped
+}
+
+const asString = (value: unknown, fallback: string, warnings: string[], path: string): string => {
+  if (value === undefined) return fallback
+  if (typeof value === "string" && value.trim().length > 0) return value.trim()
+  warnings.push(`${path} must be a non-empty string; using ${fallback}`)
+  return fallback
+}
+
+const asEnum = <T extends string>(
+  value: unknown,
+  values: ReadonlyArray<T>,
+  fallback: T,
+  warnings: string[],
+  path: string,
+): T => {
+  if (value === undefined) return fallback
+  if (typeof value === "string" && (values as ReadonlyArray<string>).includes(value)) return value as T
+  warnings.push(`${path} must be one of ${values.join(", ")}; using ${fallback}`)
+  return fallback
+}
+
+const asStringArray = (value: unknown, fallback: string[], warnings: string[], path: string): string[] => {
+  if (value === undefined) return fallback
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    warnings.push(`${path} must be an array of strings; using the previous value`)
+    return fallback
+  }
+  return [...new Set(value.map((item) => item.trim()).filter(Boolean))]
+}
+
+const validateProvider = (
+  value: unknown,
+  base: ProviderSettings,
+  warnings: string[],
+  path: string,
+): ProviderSettings => {
+  if (!isRecord(value)) {
+    warnings.push(`${path} must be an object; using defaults`)
+    return base
+  }
+  return {
+    enabled: asBoolean(value.enabled, base.enabled, warnings, `${path}.enabled`),
+    plan: asString(value.plan, base.plan, warnings, `${path}.plan`),
+    reserveMonthlyPct: asNumber(value.reserveMonthlyPct, base.reserveMonthlyPct, warnings, `${path}.reserveMonthlyPct`, 0, 90),
+    reserveWeeklyPct: asNumber(value.reserveWeeklyPct, base.reserveWeeklyPct, warnings, `${path}.reserveWeeklyPct`, 0, 90),
+    reserveFiveHourPct: asNumber(value.reserveFiveHourPct, base.reserveFiveHourPct, warnings, `${path}.reserveFiveHourPct`, 0, 90),
+    allowExtraUsage: asBoolean(value.allowExtraUsage, base.allowExtraUsage, warnings, `${path}.allowExtraUsage`),
+    probeUsage: asBoolean(value.probeUsage, base.probeUsage, warnings, `${path}.probeUsage`),
+    monthlyCreditsUsd:
+      value.monthlyCreditsUsd === undefined
+        ? base.monthlyCreditsUsd
+        : asNumber(value.monthlyCreditsUsd, base.monthlyCreditsUsd ?? 0, warnings, `${path}.monthlyCreditsUsd`, 0, 1_000_000),
+    fiveHourCapUsd:
+      value.fiveHourCapUsd === undefined
+        ? base.fiveHourCapUsd
+        : asNumber(value.fiveHourCapUsd, base.fiveHourCapUsd ?? 0, warnings, `${path}.fiveHourCapUsd`, 0, 1_000_000),
+    weeklyCapUsd:
+      value.weeklyCapUsd === undefined
+        ? base.weeklyCapUsd
+        : asNumber(value.weeklyCapUsd, base.weeklyCapUsd ?? 0, warnings, `${path}.weeklyCapUsd`, 0, 1_000_000),
+    credentialPath:
+      value.credentialPath === undefined
+        ? base.credentialPath
+        : asString(value.credentialPath, base.credentialPath ?? "", warnings, `${path}.credentialPath`) || undefined,
+    credentialSource:
+      value.credentialSource === undefined
+        ? base.credentialSource
+        : asEnum(
+            value.credentialSource,
+            ["explicit", "auto", "off"] as const,
+            base.credentialSource ?? "explicit",
+            warnings,
+            `${path}.credentialSource`,
+          ),
+    baseURL:
+      value.baseURL === undefined
+        ? base.baseURL
+        : asString(value.baseURL, base.baseURL ?? "", warnings, `${path}.baseURL`) || undefined,
+    controlBaseURL:
+      value.controlBaseURL === undefined
+        ? base.controlBaseURL
+        : asString(value.controlBaseURL, base.controlBaseURL ?? "", warnings, `${path}.controlBaseURL`) || undefined,
+    controlKeyPath:
+      value.controlKeyPath === undefined
+        ? base.controlKeyPath
+        : asString(value.controlKeyPath, base.controlKeyPath ?? "", warnings, `${path}.controlKeyPath`) || undefined,
+    /**
+     * A user-supplied reading of their own account usage. Deliberately strict:
+     * an unusable baseline is dropped with a warning rather than half-applied,
+     * because a malformed baseline would silently corrupt every quota figure.
+     */
+    baseline: (() => {
+      if (value.baseline === undefined) return base.baseline
+      if (!isRecord(value.baseline)) {
+        warnings.push(`${path}.baseline must be an object; ignoring it`)
+        return base.baseline
+      }
+      const at = timeValue(value.baseline.at)
+      if (at === undefined) {
+        warnings.push(`${path}.baseline.at must be a timestamp; ignoring the baseline`)
+        return base.baseline
+      }
+      const design = numberOr(value.baseline.designPlanUsedUsd)
+      const planModels = numberOr(value.baseline.planModelsUsedUsd)
+      const designPct = numberOr(value.baseline.designPlanUsedPct)
+      const planModelsPct = numberOr(value.baseline.planModelsUsedPct)
+      const pctOfRaw = value.baseline.pctOf
+      const pctOf = pctOfRaw === "weekly" || pctOfRaw === "monthly" ? pctOfRaw : undefined
+      if (pctOfRaw !== undefined && pctOf === undefined) {
+        warnings.push(`${path}.baseline.pctOf must be "weekly" or "monthly"; defaulting to weekly`)
+      }
+      const clampPct = (value: number | undefined) =>
+        value === undefined ? undefined : Math.min(100, Math.max(0, value))
+      if (design === undefined && planModels === undefined && designPct === undefined && planModelsPct === undefined) {
+        warnings.push(
+          `${path}.baseline needs a figure: designPlanUsedUsd, designPlanUsedPct, planModelsUsedUsd or planModelsUsedPct`,
+        )
+        return base.baseline
+      }
+      if (at > Date.now()) {
+        warnings.push(`${path}.baseline.at is in the future; ignoring the baseline`)
+        return base.baseline
+      }
+      const weeklyResetsAt = timeValue(value.baseline.weeklyResetsAt)
+      const monthlyResetsAt = timeValue(value.baseline.monthlyResetsAt)
+      const source = typeof value.baseline.source === "string" ? value.baseline.source.trim() : undefined
+      return {
+        at,
+        ...(design !== undefined ? { designPlanUsedUsd: Math.max(0, design) } : {}),
+        ...(planModels !== undefined ? { planModelsUsedUsd: Math.max(0, planModels) } : {}),
+        ...(clampPct(designPct) !== undefined ? { designPlanUsedPct: clampPct(designPct)! } : {}),
+        ...(clampPct(planModelsPct) !== undefined ? { planModelsUsedPct: clampPct(planModelsPct)! } : {}),
+        ...(pctOf ? { pctOf } : {}),
+        ...(weeklyResetsAt !== undefined ? { weeklyResetsAt } : {}),
+        ...(monthlyResetsAt !== undefined ? { monthlyResetsAt } : {}),
+        ...(source ? { source } : {}),
+      }
+    })(),
+    subscriptionOnly:
+      value.subscriptionOnly === undefined
+        ? base.subscriptionOnly
+        : asBoolean(value.subscriptionOnly, base.subscriptionOnly ?? true, warnings, `${path}.subscriptionOnly`),
+    creditsPerUsd:
+      value.creditsPerUsd === undefined
+        ? base.creditsPerUsd
+        : asNumber(value.creditsPerUsd, base.creditsPerUsd ?? 10_000, warnings, `${path}.creditsPerUsd`, 1, 10_000_000),
+    uncertaintyMarginPct:
+      value.uncertaintyMarginPct === undefined
+        ? base.uncertaintyMarginPct
+        : asNumber(
+            value.uncertaintyMarginPct,
+            base.uncertaintyMarginPct ?? 20,
+            warnings,
+            `${path}.uncertaintyMarginPct`,
+            0,
+            500,
+          ),
+    unknownQuotaPolicy:
+      value.unknownQuotaPolicy === undefined
+        ? base.unknownQuotaPolicy
+        : asEnum(
+            value.unknownQuotaPolicy,
+            ["route", "block", "ask"] as const,
+            base.unknownQuotaPolicy ?? "route",
+            warnings,
+            `${path}.unknownQuotaPolicy`,
+          ),
+    multiplierOverrides:
+      value.multiplierOverrides === undefined
+        ? base.multiplierOverrides
+        : normalizeMultiplierOverrides(value.multiplierOverrides, base.multiplierOverrides, warnings, `${path}.multiplierOverrides`),
+    providerScopedQuota:
+      value.providerScopedQuota === undefined
+        ? base.providerScopedQuota
+        : asBoolean(value.providerScopedQuota, base.providerScopedQuota ?? false, warnings, `${path}.providerScopedQuota`),
+    ignoreFiveHourWindow:
+      value.ignoreFiveHourWindow === undefined
+        ? base.ignoreFiveHourWindow
+        : asBoolean(value.ignoreFiveHourWindow, base.ignoreFiveHourWindow ?? false, warnings, `${path}.ignoreFiveHourWindow`),
+    ignoreWeeklyWindow:
+      value.ignoreWeeklyWindow === undefined
+        ? base.ignoreWeeklyWindow
+        : asBoolean(value.ignoreWeeklyWindow, base.ignoreWeeklyWindow ?? false, warnings, `${path}.ignoreWeeklyWindow`),
+  }
+}
+
+const finiteNonNegative = (value: unknown): number | undefined =>
+  typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined
+
+const normalizeMultiplierOverrides = (
+  value: unknown,
+  base: Readonly<Record<string, number>> | undefined,
+  warnings: string[],
+  path: string,
+): Readonly<Record<string, number>> | undefined => {
+  if (value === undefined) return base
+  if (!isRecord(value)) {
+    warnings.push(`${path} must be an object; using the previous value`)
+    return base
+  }
+  const out: Record<string, number> = { ...(base ?? {}) }
+  for (const [modelID, multiplier] of Object.entries(value)) {
+    const parsed = finiteNonNegative(multiplier)
+    if (parsed === undefined || parsed <= 0) {
+      warnings.push(`${path}.${modelID} must be a positive number; the entry was ignored`)
+      continue
+    }
+    out[modelID] = parsed
+  }
+  return out
+}
+
+const normalizeCostTiers = (value: unknown, index: number, warnings: string[]): CostTier[] => {
+  if (!Array.isArray(value) || value.length === 0) {
+    warnings.push(`models.definitions[${index}].cost must contain at least one tier; definition ignored`)
+    return []
+  }
+  const output: CostTier[] = []
+  value.forEach((item, tierIndex) => {
+    if (!isRecord(item)) {
+      warnings.push(`models.definitions[${index}].cost[${tierIndex}] must be an object; ignored`)
+      return
+    }
+    const input = finiteNonNegative(item.input)
+    const outputCost = finiteNonNegative(item.output)
+    if (input === undefined || outputCost === undefined) {
+      warnings.push(
+        `models.definitions[${index}].cost[${tierIndex}] needs non-negative finite input and output; ignored`,
+      )
+      return
+    }
+    const cache = isRecord(item.cache) ? item.cache : undefined
+    output.push({
+      input,
+      output: outputCost,
+      cache: {
+        read: finiteNonNegative(cache?.read) ?? 0,
+        write: finiteNonNegative(cache?.write) ?? 0,
+      },
+    })
+  })
+  return output
+}
+
+const validateDefinitions = (value: unknown, warnings: string[]): ModelDefinition[] => {
+  if (value === undefined) return []
+  if (!Array.isArray(value)) {
+    warnings.push("models.definitions must be an array; ignored")
+    return []
+  }
+  const output: ModelDefinition[] = []
+  value.forEach((entry, index) => {
+    if (!isRecord(entry)) {
+      warnings.push(`models.definitions[${index}] must be an object; ignored`)
+      return
+    }
+    const key = typeof entry.key === "string" ? entry.key.trim() : ""
+    const providerID = typeof entry.providerID === "string" ? entry.providerID.trim() : ""
+    const modelID = typeof entry.modelID === "string" ? entry.modelID.trim() : ""
+    const name = typeof entry.name === "string" ? entry.name.trim() : modelID
+    const tier = entry.tier === 1 || entry.tier === 2 || entry.tier === 3 ? entry.tier : 0
+    if (!key || !providerID || !modelID || !tier) {
+      warnings.push(`models.definitions[${index}] needs key, providerID, modelID, and tier 1-3; ignored`)
+      return
+    }
+    const input = Array.isArray(entry.input) && entry.input.every((item) => typeof item === "string") ? entry.input : ["text"]
+    const cost = normalizeCostTiers(entry.cost, index, warnings)
+    if (cost.length === 0) return
+    output.push({
+      key,
+      providerID,
+      modelID,
+      name,
+      context: Math.max(1, Number(entry.context) || 0),
+      maxOutput: Math.max(1, Number(entry.maxOutput) || 0),
+      input,
+      cost,
+      intelligence: Math.max(0, Number(entry.intelligence) || 0),
+      design: Math.max(0, Number(entry.design) || 0),
+      premium: entry.premium === true,
+      training: entry.training === true,
+      free: entry.free === true,
+      tier,
+      approved: entry.approved !== false,
+      monthlyAllowanceUsd: Math.max(0, Number(entry.monthlyAllowanceUsd) || 0),
+    })
+  })
+  return output
+}
+
+const validateModels = (value: unknown, base: ModelSettings, warnings: string[]): ModelSettings => {
+  if (value === undefined) return base
+  if (!isRecord(value)) {
+    warnings.push("models must be an object; using defaults")
+    return base
+  }
+  const overrides: Record<string, 1 | 2 | 3> = { ...base.tierOverrides }
+  if (value.tierOverrides !== undefined) {
+    if (!isRecord(value.tierOverrides)) {
+      warnings.push("models.tierOverrides must be an object; using the previous value")
+    } else {
+      for (const [key, tier] of Object.entries(value.tierOverrides)) {
+        if (tier === 1 || tier === 2 || tier === 3) overrides[key] = tier
+        else warnings.push(`models.tierOverrides.${key} must be 1, 2, or 3; ignored`)
+      }
+    }
+  }
+  return {
+    approved: asStringArray(value.approved, base.approved as string[], warnings, "models.approved"),
+    excluded: asStringArray(value.excluded, base.excluded as string[], warnings, "models.excluded"),
+    tierOverrides: overrides,
+    definitions: validateDefinitions(value.definitions, warnings),
+  }
+}
+
+/**
+ * Validate a partial settings object and merge it over a base. Unknown keys are
+ * ignored with a warning; invalid values never crash plugin startup.
+ */
+export const validateSettings = (input: unknown, base: RouterSettings = DEFAULT_SETTINGS): SettingsLoadResult => {
+  const warnings: string[] = []
+  if (!isRecord(input)) {
+    return { settings: base, warnings: ["settings must be a JSON object"], sources: [], explicitProviderEnable: new Set() }
+  }
+
+  const providers: Record<string, ProviderSettings> = { ...base.providers }
+  if (input.providers !== undefined) {
+    if (!isRecord(input.providers)) {
+      warnings.push("providers must be an object; using defaults")
+    } else {
+      for (const [id, value] of Object.entries(input.providers)) {
+        providers[id] = validateProvider(value, providers[id] ?? providerDefaults("custom"), warnings, `providers.${id}`)
+      }
+    }
+  }
+
+  const privacyInput = isRecord(input.privacy) ? input.privacy : {}
+  const privacy: PrivacySettings = {
+    allowTrainingModels: asBoolean(
+      privacyInput.allowTrainingModels,
+      base.privacy.allowTrainingModels,
+      warnings,
+      "privacy.allowTrainingModels",
+    ),
+    allowFreeModels: asBoolean(privacyInput.allowFreeModels, base.privacy.allowFreeModels, warnings, "privacy.allowFreeModels"),
+    requireZdr: asBoolean(privacyInput.requireZdr, base.privacy.requireZdr, warnings, "privacy.requireZdr"),
+  }
+
+  const premiumInput = isRecord(input.premium) ? input.premium : {}
+  const premium: PremiumSettings = {
+    mode: asEnum(premiumInput.mode, ["off", "ask", "allowed", "auto"] as const, base.premium.mode, warnings, "premium.mode"),
+    monthlyBudgetUsd: asNumber(
+      premiumInput.monthlyBudgetUsd,
+      base.premium.monthlyBudgetUsd,
+      warnings,
+      "premium.monthlyBudgetUsd",
+      0,
+      100_000,
+    ),
+    oneShotApproval: asBoolean(premiumInput.oneShotApproval, base.premium.oneShotApproval, warnings, "premium.oneShotApproval"),
+  }
+
+  const routingInput = isRecord(input.routing) ? input.routing : {}
+  const routing = {
+    intelligenceFloor: asNumber(
+      routingInput.intelligenceFloor,
+      base.routing.intelligenceFloor,
+      warnings,
+      "routing.intelligenceFloor",
+      0,
+      100,
+    ),
+    designFloor: asNumber(routingInput.designFloor, base.routing.designFloor, warnings, "routing.designFloor", 0, 100),
+    sophisticatedDesignFloor: asNumber(
+      routingInput.sophisticatedDesignFloor,
+      base.routing.sophisticatedDesignFloor,
+      warnings,
+      "routing.sophisticatedDesignFloor",
+      0,
+      100,
+    ),
+    switchHysteresisPct: asNumber(
+      routingInput.switchHysteresisPct,
+      base.routing.switchHysteresisPct,
+      warnings,
+      "routing.switchHysteresisPct",
+      0,
+      100,
+    ),
+    largeContextTokens: asNumber(
+      routingInput.largeContextTokens,
+      base.routing.largeContextTokens,
+      warnings,
+      "routing.largeContextTokens",
+      10_000,
+      5_000_000,
+    ),
+    largeContextHysteresisPct: asNumber(
+      routingInput.largeContextHysteresisPct,
+      base.routing.largeContextHysteresisPct,
+      warnings,
+      "routing.largeContextHysteresisPct",
+      0,
+      100,
+    ),
+    maxEscalationsPerTask: asNumber(
+      routingInput.maxEscalationsPerTask,
+      base.routing.maxEscalationsPerTask,
+      warnings,
+      "routing.maxEscalationsPerTask",
+      0,
+      5,
+    ),
+    preferSameProvider: asBoolean(
+      routingInput.preferSameProvider,
+      base.routing.preferSameProvider,
+      warnings,
+      "routing.preferSameProvider",
+    ),
+    failClosed: asBoolean(routingInput.failClosed, base.routing.failClosed, warnings, "routing.failClosed"),
+    protectEscalationPool: asBoolean(
+      routingInput.protectEscalationPool,
+      base.routing.protectEscalationPool,
+      warnings,
+      "routing.protectEscalationPool",
+    ),
+    longContextFloorTokens: asNumber(
+      routingInput.longContextFloorTokens,
+      base.routing.longContextFloorTokens,
+      warnings,
+      "routing.longContextFloorTokens",
+      10_000,
+      10_000_000,
+    ),
+    // Opt-in. Defaults to off so an upgrade cannot change routing behavior on
+    // its own; the owner turns it on after seeing what it would pick.
+    calibrateFloor: asBoolean(
+      routingInput.calibrateFloor,
+      base.routing.calibrateFloor ?? false,
+      warnings,
+      "routing.calibrateFloor",
+    ),
+  }
+
+  const quotaInput = isRecord(input.quota) ? input.quota : {}
+  const quota = {
+    probeOpenCodeGo: asBoolean(quotaInput.probeOpenCodeGo, base.quota.probeOpenCodeGo, warnings, "quota.probeOpenCodeGo"),
+    probeCommandCode: asBoolean(quotaInput.probeCommandCode, base.quota.probeCommandCode, warnings, "quota.probeCommandCode"),
+    probeOpenDesign: asBoolean(quotaInput.probeOpenDesign, base.quota.probeOpenDesign, warnings, "quota.probeOpenDesign"),
+    probeIntervalMinutes: asNumber(
+      quotaInput.probeIntervalMinutes,
+      base.quota.probeIntervalMinutes,
+      warnings,
+      "quota.probeIntervalMinutes",
+      0,
+      1440,
+    ),
+    bootstrapSessions: asNumber(
+      quotaInput.bootstrapSessions,
+      base.quota.bootstrapSessions,
+      warnings,
+      "quota.bootstrapSessions",
+      0,
+      500,
+    ),
+    bootstrapDays: asNumber(quotaInput.bootstrapDays, base.quota.bootstrapDays, warnings, "quota.bootstrapDays", 0, 365),
+  }
+
+  const healthInput = isRecord(input.contextHealth) ? input.contextHealth : {}
+  const contextHealth = {
+    enabled: asBoolean(healthInput.enabled, base.contextHealth.enabled, warnings, "contextHealth.enabled"),
+    warnAtTokens: asNumber(
+      healthInput.warnAtTokens,
+      base.contextHealth.warnAtTokens,
+      warnings,
+      "contextHealth.warnAtTokens",
+      10_000,
+      10_000_000,
+    ),
+    recommendAtTokens: asNumber(
+      healthInput.recommendAtTokens,
+      base.contextHealth.recommendAtTokens,
+      warnings,
+      "contextHealth.recommendAtTokens",
+      10_000,
+      10_000_000,
+    ),
+  }
+
+  const uiInput = isRecord(input.ui) ? input.ui : {}
+  const compactToggle = asBoolean(
+    uiInput.compactMode ?? uiInput.compact ?? input.compactMode ?? input.compact,
+    base.ui.compactMode || base.ui.compact,
+    warnings,
+    "ui.compactMode",
+  )
+  const ui = {
+    notifications: asBoolean(uiInput.notifications, base.ui.notifications, warnings, "ui.notifications"),
+    compactMode: compactToggle,
+    compact: compactToggle,
+  }
+
+  const loggingInput = isRecord(input.logging) ? input.logging : {}
+  const logging = {
+    storePromptText: asBoolean(loggingInput.storePromptText, base.logging.storePromptText, warnings, "logging.storePromptText"),
+    decisionLogSize: asNumber(
+      loggingInput.decisionLogSize,
+      base.logging.decisionLogSize,
+      warnings,
+      "logging.decisionLogSize",
+      10,
+      2000,
+    ),
+    diagnostics: asBoolean(loggingInput.diagnostics, base.logging.diagnostics, warnings, "logging.diagnostics"),
+  }
+
+  const contextInput = isRecord(input.contextManagement) ? input.contextManagement : {}
+  const contextManagement = {
+    mode: asEnum(
+      contextInput.mode,
+      ["native", "conservative", "budget-optimized"] as const,
+      base.contextManagement.mode,
+      warnings,
+      "contextManagement.mode",
+    ),
+    enabled: asBoolean(contextInput.enabled, base.contextManagement.enabled, warnings, "contextManagement.enabled"),
+    compactAtTokens: asNumber(
+      contextInput.compactAtTokens,
+      base.contextManagement.compactAtTokens,
+      warnings,
+      "contextManagement.compactAtTokens",
+      0,
+      10_000_000,
+    ),
+    cooldownMinutes: asNumber(
+      contextInput.cooldownMinutes,
+      base.contextManagement.cooldownMinutes,
+      warnings,
+      "contextManagement.cooldownMinutes",
+      1,
+      1440,
+    ),
+    allowEmergencyCompaction: asBoolean(
+      contextInput.allowEmergencyCompaction,
+      base.contextManagement.allowEmergencyCompaction,
+      warnings,
+      "contextManagement.allowEmergencyCompaction",
+    ),
+  }
+
+  const speedInput = isRecord(input.speed) ? input.speed : {}
+  const speed = {
+    enabled: asBoolean(speedInput.enabled, base.speed.enabled, warnings, "speed.enabled"),
+    weightPct: asNumber(speedInput.weightPct, base.speed.weightPct, warnings, "speed.weightPct", 0, 100),
+    minSamples: asNumber(speedInput.minSamples, base.speed.minSamples, warnings, "speed.minSamples", 1, 500),
+    slowRouteMultiple: asNumber(
+      speedInput.slowRouteMultiple,
+      base.speed.slowRouteMultiple,
+      warnings,
+      "speed.slowRouteMultiple",
+      1,
+      20,
+    ),
+  }
+
+  if (contextManagement.mode === "budget-optimized" && contextManagement.compactAtTokens <= 0) {
+    warnings.push(
+      "contextManagement.mode is budget-optimized but compactAtTokens is 0; only the cheapest route's verified window will trigger compaction",
+    )
+  }
+
+  const offline = validateOffline(input.offline, base.offline, warnings)
+
+  const settings: RouterSettings = {
+    enabled: asBoolean(input.enabled, base.enabled, warnings, "enabled"),
+    mode: asEnum(input.mode, ["efficiency", "balanced", "premium"] as const, base.mode, warnings, "mode"),
+    dryRun: asBoolean(input.dryRun, base.dryRun, warnings, "dryRun"),
+    compactMode: compactToggle,
+    compact: compactToggle,
+    providers,
+    privacy,
+    premium,
+    routing,
+    quota,
+    contextHealth,
+    contextManagement,
+    speed,
+    ui,
+    logging,
+    models: validateModels(input.models, base.models, warnings),
+    offline,
+  }
+
+  if (settings.premium.mode === "allowed" && settings.premium.monthlyBudgetUsd <= 0) {
+    warnings.push("premium.mode is allowed but premium.monthlyBudgetUsd is 0; premium remains unavailable")
+  }
+
+  return { settings, warnings, sources: [], explicitProviderEnable: new Set() }
+}
+
+/**
+ * Validate the offline block.
+ *
+ * Kept separate from the main validator because offline mode has its own
+ * failure mode: a misconfigured endpoint or model store must be a loud warning
+ * rather than a silent default, since a silent default here is a model loaded
+ * onto the wrong disk or a session pointed at a hosted URL.
+ */
+const validateOffline = (
+  input: unknown,
+  base: OfflineSettings | undefined,
+  warnings: string[],
+): OfflineSettings => {
+  const resolved = base ?? DEFAULT_OFFLINE_SETTINGS
+  if (input === undefined) return resolved
+  if (!isRecord(input)) {
+    warnings.push("offline must be an object; using defaults")
+    return resolved
+  }
+  const modelInput = isRecord(input.model) ? input.model : {}
+  const modelBase = resolved.model
+
+  const baseURL = typeof modelInput.baseURL === "string" && modelInput.baseURL.trim()
+    ? modelInput.baseURL.trim()
+    : modelBase.baseURL
+  if (!isLoopbackURL(baseURL)) {
+    // A routable address here would expose prompts and model control to the
+    // local network, and would also mean the "local" endpoint might not be
+    // local at all. Refuse it and fall back to loopback.
+    warnings.push(
+      `offline.model.baseURL ${baseURL} is not a loopback address; using ${modelBase.baseURL}. Offline mode must not reach a routable endpoint.`,
+    )
+  }
+
+  const modelName = typeof modelInput.model === "string" && modelInput.model.trim()
+    ? modelInput.model.trim()
+    : modelBase.model
+
+  const contextTokens = asNumber(
+    modelInput.contextTokens,
+    modelBase.contextTokens,
+    warnings,
+    "offline.model.contextTokens",
+    1_024,
+    131_072,
+  )
+  if (contextTokens < MINIMUM_OFFLINE_CONTEXT) {
+    warnings.push(
+      `offline.model.contextTokens is ${contextTokens}, below the ${MINIMUM_OFFLINE_CONTEXT} needed for a screenshot-driven edit`,
+    )
+  }
+
+  const storeInput = input.modelStorePath
+  let modelStorePath: string | undefined
+  if (typeof storeInput === "string" && storeInput.trim()) {
+    modelStorePath = storeInput.trim()
+  } else if (storeInput !== undefined) {
+    warnings.push("offline.modelStorePath must be a non-empty string; ignored")
+  }
+
+  return {
+    enabled: asBoolean(input.enabled, resolved.enabled, warnings, "offline.enabled"),
+    ...(modelStorePath ? { modelStorePath } : {}),
+    model: {
+      model: modelName,
+      baseURL: isLoopbackURL(baseURL) ? baseURL : modelBase.baseURL,
+      contextTokens,
+      maxOutputTokens: asNumber(
+        modelInput.maxOutputTokens,
+        modelBase.maxOutputTokens,
+        warnings,
+        "offline.model.maxOutputTokens",
+        128,
+        32_768,
+      ),
+      concurrency: asNumber(
+        modelInput.concurrency,
+        modelBase.concurrency,
+        warnings,
+        "offline.model.concurrency",
+        1,
+        4,
+      ),
+      keepAliveMinutes: asNumber(
+        modelInput.keepAliveMinutes,
+        modelBase.keepAliveMinutes,
+        warnings,
+        "offline.model.keepAliveMinutes",
+        0,
+        120,
+      ),
+      vision: asBoolean(modelInput.vision, modelBase.vision, warnings, "offline.model.vision"),
+      tools: asBoolean(modelInput.tools, modelBase.tools, warnings, "offline.model.tools"),
+    },
+  }
+}
+
+/**
+ * Project files may tighten privacy or spending, but they cannot loosen global
+ * policy. This protects a work repository from enabling training models or
+ * premium spend through a checked-in config file.
+ */
+export const applyProjectGuardrails = (
+  globalSettings: RouterSettings,
+  projectInput: unknown,
+  warnings: string[],
+): RouterSettings => {
+  const candidate = validateSettings(projectInput, globalSettings).settings
+  const tightened: RouterSettings = {
+    ...candidate,
+    enabled: globalSettings.enabled && candidate.enabled,
+    privacy: {
+      allowTrainingModels: globalSettings.privacy.allowTrainingModels && candidate.privacy.allowTrainingModels,
+      allowFreeModels: globalSettings.privacy.allowFreeModels && candidate.privacy.allowFreeModels,
+      requireZdr: globalSettings.privacy.requireZdr || candidate.privacy.requireZdr,
+    },
+    premium: {
+      ...candidate.premium,
+      mode:
+        globalSettings.premium.mode === "off" || candidate.premium.mode === "off"
+          ? "off"
+          : globalSettings.premium.mode === "ask" || candidate.premium.mode === "ask"
+            ? "ask"
+            : globalSettings.premium.mode === "auto" && candidate.premium.mode === "auto"
+              ? "auto"
+              : "allowed",
+      monthlyBudgetUsd: Math.min(globalSettings.premium.monthlyBudgetUsd, candidate.premium.monthlyBudgetUsd),
+    },
+    providers: Object.fromEntries(
+      Object.entries(candidate.providers).map(([id, provider]) => {
+        const globalProvider = globalSettings.providers[id]
+        if (!globalProvider) return [id, { ...provider, enabled: false, allowExtraUsage: false }]
+        return [
+          id,
+          {
+            ...provider,
+            enabled: globalProvider.enabled && provider.enabled,
+            allowExtraUsage: globalProvider.allowExtraUsage && provider.allowExtraUsage,
+          },
+        ]
+      }),
+    ),
+  }
+
+  if (candidate.privacy.allowTrainingModels && !globalSettings.privacy.allowTrainingModels) {
+    warnings.push("Project config tried to enable training models; global privacy setting kept it disabled")
+  }
+  if (
+    (candidate.premium.mode === "allowed" || candidate.premium.mode === "auto") &&
+    globalSettings.premium.mode !== candidate.premium.mode
+  ) {
+    warnings.push("Project config tried to enable automatic premium routing; global setting kept it restricted")
+  }
+  return tightened
+}
+
+const readJson = (path: string, warnings: string[]): unknown | undefined => {
+  if (!existsSync(path)) return undefined
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as unknown
+  } catch (error) {
+    warnings.push(`Could not read ${path}: ${error instanceof Error ? error.message : String(error)}`)
+    return undefined
+  }
+}
+
+export interface LoadSettingsInput {
+  options?: unknown
+  directory?: string
+  home?: string
+  projectDirectory?: string
+}
+
+export const loadSettings = (input: LoadSettingsInput = {}): SettingsLoadResult => {
+  const warnings: string[] = []
+  const sources: string[] = []
+  const home = input.home ?? homedir()
+  const globalPath = join(home, ".config", "opencode", "smart-router.json")
+
+  let settings = DEFAULT_SETTINGS
+  const explicit = new Set<string>()
+
+  if (input.options !== undefined) {
+    const validated = validateSettings(input.options, settings)
+    settings = validated.settings
+    // Validation warnings used to be thrown away here, so a malformed option was
+    // repaired silently and the user never learned why their setting did nothing.
+    warnings.push(...validated.warnings)
+    sources.push("plugin options")
+    for (const id of explicitProviderEnable(input.options)) explicit.add(id)
+  }
+
+  const globalInput = readJson(globalPath, warnings)
+  if (globalInput !== undefined) {
+    const validated = validateSettings(globalInput, settings)
+    settings = validated.settings
+    warnings.push(...validated.warnings)
+    sources.push(globalPath)
+    for (const id of explicitProviderEnable(globalInput)) explicit.add(id)
+  }
+
+  const projectDirectory = input.projectDirectory ?? input.directory
+  if (projectDirectory) {
+    const projectPath = join(projectDirectory, ".opencode", "smart-router.json")
+    const projectInput = readJson(projectPath, warnings)
+    if (projectInput !== undefined) {
+      settings = applyProjectGuardrails(settings, projectInput, warnings)
+      sources.push(projectPath)
+      for (const id of explicitProviderEnable(projectInput)) explicit.add(id)
+    }
+  }
+
+  return { settings, warnings, sources, explicitProviderEnable: explicit }
+}