@yycholla/pi-dynamic-workflows 3.3.0

package/src/model-routing.ts

@@ -0,0 +1,73 @@
+/**
+ * Per-stage model routing for workflows.
+ * Allows different phases to use different models.
+ */
+
+export interface ModelRoute {
+  /** Phase name pattern (regex or exact match). */
+  phasePattern: string;
+  /** Model to use for this phase. */
+  model: string;
+  /** Whether to use regex matching. */
+  useRegex?: boolean;
+}
+
+export interface ModelRoutingConfig {
+  /** Default model for all phases. */
+  defaultModel?: string;
+  /** Per-phase model overrides. */
+  routes: ModelRoute[];
+}
+
+/**
+ * Resolve which model to use for a given phase.
+ */
+export function resolveModelForPhase(phase: string | undefined, config: ModelRoutingConfig): string | undefined {
+  if (!phase || !config.routes.length) {
+    return config.defaultModel;
+  }
+
+  for (const route of config.routes) {
+    if (route.useRegex) {
+      try {
+        const regex = new RegExp(route.phasePattern, "i");
+        if (regex.test(phase)) {
+          return route.model;
+        }
+      } catch {
+        // Invalid regex, skip
+      }
+    } else if (phase === route.phasePattern) {
+      // Exact, case-sensitive match — phase titles are author-controlled literals,
+      // so fuzzy substring matching only caused mis-routes (e.g. "analyze" matching
+      // "analyze-deep" or vice-versa). Use the regex branch for fuzzy needs.
+      return route.model;
+    }
+  }
+
+  return config.defaultModel;
+}
+
+/**
+ * Parse model routing from workflow meta: per-phase models from meta.phases[].model
+ * and a top-level default from meta.model (used when no phase route matches).
+ */
+export function parseModelRoutingFromMeta(
+  phases?: Array<{ title: string; model?: string }>,
+  defaultModel?: string,
+): ModelRoutingConfig {
+  const routes: ModelRoute[] = [];
+
+  if (phases) {
+    for (const phase of phases) {
+      if (phase.model) {
+        routes.push({
+          phasePattern: phase.title,
+          model: phase.model,
+        });
+      }
+    }
+  }
+
+  return { defaultModel, routes };
+}

package/src/model-spec.ts

@@ -0,0 +1,309 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+
+export type ModelThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export interface ResolvedModelSpec {
+  requestedSpec: string;
+  model?: Model<Api>;
+  thinkingLevel?: ModelThinkingLevel;
+  resolvedSpec?: string;
+  warning?: string;
+  error?: string;
+}
+
+interface ParseModelPatternOptions {
+  allowInvalidThinkingLevelFallback?: boolean;
+}
+
+interface ParsedModelPattern {
+  model?: Model<Api>;
+  thinkingLevel?: ModelThinkingLevel;
+  warning?: string;
+}
+
+const DEFAULT_MODEL_PER_PROVIDER: Record<string, string> = {
+  "amazon-bedrock": "us.anthropic.claude-opus-4-6-v1",
+  anthropic: "claude-opus-4-8",
+  openai: "gpt-5.4",
+  "azure-openai-responses": "gpt-5.4",
+  "openai-codex": "gpt-5.5",
+  deepseek: "deepseek-v4-pro",
+  google: "gemini-3.1-pro-preview",
+  "google-vertex": "gemini-3.1-pro-preview",
+  "github-copilot": "gpt-5.4",
+  openrouter: "moonshotai/kimi-k2.6",
+  "vercel-ai-gateway": "zai/glm-5.1",
+  zai: "glm-5.1",
+  mistral: "devstral-medium-latest",
+  minimax: "MiniMax-M2.7",
+  "minimax-cn": "MiniMax-M2.7",
+  moonshotai: "kimi-k2.6",
+  "moonshotai-cn": "kimi-k2.6",
+  huggingface: "moonshotai/Kimi-K2.6",
+  fireworks: "accounts/fireworks/models/kimi-k2p6",
+  together: "moonshotai/Kimi-K2.6",
+  opencode: "kimi-k2.6",
+  "opencode-go": "kimi-k2.6",
+  "kimi-coding": "kimi-for-coding",
+  "cloudflare-workers-ai": "@cf/moonshotai/kimi-k2.6",
+  "cloudflare-ai-gateway": "workers-ai/@cf/moonshotai/kimi-k2.6",
+  xiaomi: "mimo-v2.5-pro",
+  "xiaomi-token-plan-cn": "mimo-v2.5-pro",
+  "xiaomi-token-plan-ams": "mimo-v2.5-pro",
+  "xiaomi-token-plan-sgp": "mimo-v2.5-pro",
+};
+
+export function isThinkingLevel(value: string): value is ModelThinkingLevel {
+  return (THINKING_LEVELS as readonly string[]).includes(value);
+}
+
+export function formatModelSpecWithThinking(modelSpec: string, thinkingLevel: ModelThinkingLevel | undefined): string {
+  return thinkingLevel ? `${modelSpec}:${thinkingLevel}` : modelSpec;
+}
+
+export function canonicalModelSpec(model: Model<Api>): string {
+  return `${model.provider}/${model.id}`;
+}
+
+/**
+ * Split a stored tier spec for display/editing. Exact known model specs win, so
+ * model ids that legitimately contain colons are not mistaken for thinking.
+ */
+export function splitModelSpecThinking(
+  spec: string | undefined,
+  knownModelSpecs?: readonly string[],
+): { modelSpec: string; thinkingLevel?: ModelThinkingLevel } {
+  const trimmed = spec?.trim() ?? "";
+  if (!trimmed) return { modelSpec: "", thinkingLevel: undefined };
+
+  const known = knownModelSpecs ? new Set(knownModelSpecs) : undefined;
+  if (known?.has(trimmed)) return { modelSpec: trimmed, thinkingLevel: undefined };
+
+  const lastColon = trimmed.lastIndexOf(":");
+  if (lastColon === -1) return { modelSpec: trimmed, thinkingLevel: undefined };
+
+  const prefix = trimmed.slice(0, lastColon);
+  const suffix = trimmed.slice(lastColon + 1);
+  if (!prefix || !isThinkingLevel(suffix)) return { modelSpec: trimmed, thinkingLevel: undefined };
+  if (known && !known.has(prefix)) return { modelSpec: trimmed, thinkingLevel: undefined };
+  return { modelSpec: prefix, thinkingLevel: suffix };
+}
+
+function isAlias(id: string): boolean {
+  if (id.endsWith("-latest")) return true;
+  return !/-\d{8}$/.test(id);
+}
+
+function findExactModelReferenceMatch(modelReference: string, availableModels: Model<Api>[]): Model<Api> | undefined {
+  const trimmedReference = modelReference.trim();
+  if (!trimmedReference) return undefined;
+  const normalizedReference = trimmedReference.toLowerCase();
+
+  const canonicalMatches = availableModels.filter(
+    (model) => canonicalModelSpec(model).toLowerCase() === normalizedReference,
+  );
+  if (canonicalMatches.length === 1) return canonicalMatches[0];
+  if (canonicalMatches.length > 1) return undefined;
+
+  const slashIndex = trimmedReference.indexOf("/");
+  if (slashIndex !== -1) {
+    const provider = trimmedReference.slice(0, slashIndex).trim();
+    const modelId = trimmedReference.slice(slashIndex + 1).trim();
+    if (provider && modelId) {
+      const providerMatches = availableModels.filter(
+        (model) =>
+          model.provider.toLowerCase() === provider.toLowerCase() && model.id.toLowerCase() === modelId.toLowerCase(),
+      );
+      if (providerMatches.length === 1) return providerMatches[0];
+      if (providerMatches.length > 1) return undefined;
+    }
+  }
+
+  const idMatches = availableModels.filter((model) => model.id.toLowerCase() === normalizedReference);
+  return idMatches.length === 1 ? idMatches[0] : undefined;
+}
+
+function tryMatchModel(modelPattern: string, availableModels: Model<Api>[]): Model<Api> | undefined {
+  const exactMatch = findExactModelReferenceMatch(modelPattern, availableModels);
+  if (exactMatch) return exactMatch;
+
+  const normalizedPattern = modelPattern.toLowerCase();
+  const matches = availableModels.filter(
+    (model) =>
+      model.id.toLowerCase().includes(normalizedPattern) || model.name?.toLowerCase().includes(normalizedPattern),
+  );
+  if (matches.length === 0) return undefined;
+
+  const aliases = matches.filter((model) => isAlias(model.id));
+  if (aliases.length > 0) {
+    aliases.sort((a, b) => b.id.localeCompare(a.id));
+    return aliases[0];
+  }
+
+  const datedVersions = matches.filter((model) => !isAlias(model.id));
+  datedVersions.sort((a, b) => b.id.localeCompare(a.id));
+  return datedVersions[0];
+}
+
+function parseModelPattern(
+  pattern: string,
+  availableModels: Model<Api>[],
+  options?: ParseModelPatternOptions,
+): ParsedModelPattern {
+  const exactMatch = tryMatchModel(pattern, availableModels);
+  if (exactMatch) return { model: exactMatch };
+
+  const lastColonIndex = pattern.lastIndexOf(":");
+  if (lastColonIndex === -1) return {};
+
+  const prefix = pattern.slice(0, lastColonIndex);
+  const suffix = pattern.slice(lastColonIndex + 1);
+  if (isThinkingLevel(suffix)) {
+    const result = parseModelPattern(prefix, availableModels, options);
+    if (!result.model) return result;
+    return {
+      model: result.model,
+      thinkingLevel: result.warning ? undefined : suffix,
+      warning: result.warning,
+    };
+  }
+
+  if (options?.allowInvalidThinkingLevelFallback === false) return {};
+
+  const result = parseModelPattern(prefix, availableModels, options);
+  if (!result.model) return result;
+  return {
+    model: result.model,
+    warning: `Invalid thinking level "${suffix}" in pattern "${pattern}". Using default instead.`,
+  };
+}
+
+function buildFallbackModel(provider: string, modelId: string, availableModels: Model<Api>[]): Model<Api> | undefined {
+  const providerModels = availableModels.filter((model) => model.provider === provider);
+  if (providerModels.length === 0) return undefined;
+  const defaultId = DEFAULT_MODEL_PER_PROVIDER[provider];
+  const baseModel = defaultId
+    ? (providerModels.find((model) => model.id === defaultId) ?? providerModels[0])
+    : providerModels[0];
+  return { ...baseModel, id: modelId, name: modelId };
+}
+
+/**
+ * Resolve a workflow model-tier/agent model string with the same user-facing
+ * grammar as Pi CLI `--model`: `provider/modelId[:thinking]`, bare model ids,
+ * fuzzy patterns, and exact colon-containing model ids.
+ */
+export function resolveModelSpecWithThinking(
+  spec: string,
+  modelRegistry: Pick<ModelRegistry, "getAll">,
+): ResolvedModelSpec {
+  const requestedSpec = spec.trim();
+  if (!requestedSpec) return { requestedSpec, error: "No model spec provided." };
+
+  const availableModels = modelRegistry.getAll();
+  if (availableModels.length === 0) {
+    return {
+      requestedSpec,
+      error: "No models available. Check your installation or add models to models.json.",
+    };
+  }
+
+  const providerMap = new Map<string, string>();
+  for (const model of availableModels) {
+    providerMap.set(model.provider.toLowerCase(), model.provider);
+  }
+
+  let provider: string | undefined;
+  let pattern = requestedSpec;
+  let inferredProvider = false;
+  const slashIndex = requestedSpec.indexOf("/");
+  if (slashIndex !== -1) {
+    const maybeProvider = requestedSpec.slice(0, slashIndex);
+    const canonicalProvider = providerMap.get(maybeProvider.toLowerCase());
+    if (canonicalProvider) {
+      provider = canonicalProvider;
+      pattern = requestedSpec.slice(slashIndex + 1);
+      inferredProvider = true;
+    }
+  }
+
+  if (!provider) {
+    const exact = findExactModelReferenceMatch(requestedSpec, availableModels);
+    if (exact) {
+      return { requestedSpec, model: exact, resolvedSpec: canonicalModelSpec(exact) };
+    }
+  }
+
+  const candidates = provider ? availableModels.filter((model) => model.provider === provider) : availableModels;
+  const { model, thinkingLevel, warning } = parseModelPattern(pattern, candidates, {
+    allowInvalidThinkingLevelFallback: false,
+  });
+  if (model) {
+    return {
+      requestedSpec,
+      model,
+      thinkingLevel,
+      warning,
+      resolvedSpec: formatModelSpecWithThinking(canonicalModelSpec(model), thinkingLevel),
+    };
+  }
+
+  if (inferredProvider) {
+    const exact = findExactModelReferenceMatch(requestedSpec, availableModels);
+    if (exact) {
+      return { requestedSpec, model: exact, resolvedSpec: canonicalModelSpec(exact) };
+    }
+
+    const fallback = parseModelPattern(requestedSpec, availableModels, {
+      allowInvalidThinkingLevelFallback: false,
+    });
+    if (fallback.model) {
+      return {
+        requestedSpec,
+        model: fallback.model,
+        thinkingLevel: fallback.thinkingLevel,
+        warning: fallback.warning,
+        resolvedSpec: formatModelSpecWithThinking(canonicalModelSpec(fallback.model), fallback.thinkingLevel),
+      };
+    }
+  }
+
+  if (provider) {
+    let fallbackPattern = pattern;
+    let fallbackThinking: ModelThinkingLevel | undefined;
+    const lastColon = pattern.lastIndexOf(":");
+    if (lastColon !== -1) {
+      const suffix = pattern.slice(lastColon + 1);
+      if (isThinkingLevel(suffix)) {
+        fallbackPattern = pattern.slice(0, lastColon);
+        fallbackThinking = suffix;
+      }
+    }
+
+    const fallbackModel = buildFallbackModel(provider, fallbackPattern, availableModels);
+    if (fallbackModel) {
+      const modelWithReasoning =
+        fallbackThinking && fallbackThinking !== "off" ? { ...fallbackModel, reasoning: true } : fallbackModel;
+      const fallbackWarning = warning
+        ? `${warning} Model "${fallbackPattern}" not found for provider "${provider}". Using custom model id.`
+        : `Model "${fallbackPattern}" not found for provider "${provider}". Using custom model id.`;
+      return {
+        requestedSpec,
+        model: modelWithReasoning,
+        thinkingLevel: fallbackThinking,
+        warning: fallbackWarning,
+        resolvedSpec: formatModelSpecWithThinking(canonicalModelSpec(modelWithReasoning), fallbackThinking),
+      };
+    }
+  }
+
+  const display = provider ? `${provider}/${pattern}` : requestedSpec;
+  return {
+    requestedSpec,
+    warning,
+    error: `Model "${display}" not found. Use /workflows-models to choose an available model.`,
+  };
+}

package/src/model-tier-config.ts

@@ -0,0 +1,296 @@
+/**
+ * Model tier configuration for workflow subagent model routing.
+ *
+ * A tier is a named slot (small/medium/big) holding exactly ONE model spec
+ * string (e.g. "openai/gpt-4.1-mini" or "openai-codex/gpt-5.5:xhigh").
+ * When an agent() call specifies opts.tier, that single model is resolved with
+ * Pi CLI-style parsing and used as the subagent's model/thinking level (unless
+ * an explicit opts.model is given, which always wins — see agent.ts).
+ *
+ * This augments the phase-pattern routing in model-routing.ts: phase routing
+ * maps workflow phases → models via the script's meta; tiers give scripts a
+ * coarse, user-configurable small/medium/big knob that is independent of any
+ * concrete provider/model id.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { listAvailableModels } from "./agent.js";
+import { MODEL_TIERS_FILE } from "./config.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Model tier configuration. Maps tier names (e.g. "small", "medium", "big")
+ * to a single model spec string (e.g. "gpt-4.1-mini", "openai/gpt-4.1-mini",
+ * or "openai-codex/gpt-5.5:xhigh").
+ */
+export interface ModelTierConfig {
+  tiers: Record<string, string>;
+}
+
+/**
+ * The minimal projection of a model that tier ranking needs. Deliberately NOT
+ * the SDK's full `Model` type: tier logic depends only on these three fields,
+ * so it stays decoupled from the SDK (no `@earendil-works/pi-ai` import here)
+ * and is trivially unit-testable with plain objects. `agent.ts`'s
+ * `listAvailableModels()` produces these from the live registry.
+ */
+export interface RankableModel {
+  /** Canonical "provider/id" spec string. */
+  spec: string;
+  /** Per-token output price, if the registry reports one. Missing or 0 = unknown. */
+  costOutput?: number;
+  /** Context window size, if the registry reports one. */
+  contextWindow?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Configuration path
+// ---------------------------------------------------------------------------
+
+/** Path to the model tiers JSON config file (~/.pi/workflows/model-tiers.json). */
+export function getModelTierConfigPath(): string {
+  return join(homedir(), MODEL_TIERS_FILE);
+}
+
+// ---------------------------------------------------------------------------
+// Capability signal
+// ---------------------------------------------------------------------------
+
+/**
+ * Substrings that identify small/cheap models (case-insensitive), used only as
+ * a fallback capability hint when price signals are absent or tied.
+ */
+export const SMALL_MODEL_HINTS = ["mini", "flash", "haiku", "nano", "small"] as const;
+
+/**
+ * Substrings that identify large/capable models (case-insensitive), used only
+ * as a fallback capability hint when price signals are absent or tied.
+ */
+export const BIG_MODEL_HINTS = ["opus", "pro", "ultra", "large", "plus"] as const;
+
+/**
+ * Fallback capability hint from a model's name: -1 for a small/cheap name, +1
+ * for a large/capable name, 0 otherwise. If a name matches both sets, the small
+ * hint wins (we never want a "mini"-labelled model to outrank a neutral or
+ * clearly-large one). This is only a FALLBACK: `rankByCapability` prefers the
+ * registry's price signal, which is robust to new vendor names (e.g. "fable",
+ * "mimo") that match no hint and would otherwise all score 0.
+ */
+export function hintScore(spec: string): number {
+  const lower = spec.toLowerCase();
+  if (SMALL_MODEL_HINTS.some((hint) => lower.includes(hint))) return -1;
+  if (BIG_MODEL_HINTS.some((hint) => lower.includes(hint))) return 1;
+  return 0;
+}
+
+/**
+ * Rank models from least → most capable.
+ *
+ * PRIMARY signal is output price (higher price ≈ more capable): within a single
+ * registry, price tracks the vendor's capability tier far more robustly than
+ * model-name substrings, and it works for models whose names match no hint.
+ *
+ * Models with an UNKNOWN price (missing or 0 — common for self-hosted
+ * `models.json` entries) are NOT treated as "cheapest = weakest". Instead they
+ * are projected onto the known price range via their substring hint: a
+ * big-hint name lands at the top of the range, a small-hint name at the bottom,
+ * a neutral name at the middle. When NO model has a known price at all, this
+ * degrades to pure hint ordering (the previous behavior).
+ *
+ * The comparison is a single total order (projected cost → hint → contextWindow
+ * → stable registry index), so the sort is transitive and stable.
+ */
+export function rankByCapability(models: readonly RankableModel[]): RankableModel[] {
+  const knownCosts = models
+    .map((m) => m.costOutput)
+    .filter((c): c is number => typeof c === "number" && c > 0)
+    .sort((a, b) => a - b);
+  const hasPriceSignal = knownCosts.length > 0;
+  const min = knownCosts[0];
+  const max = knownCosts[knownCosts.length - 1];
+  const median = knownCosts[Math.floor(knownCosts.length / 2)];
+
+  // Project every model onto the price axis. Undefined only when there is no
+  // price signal anywhere (all models unpriced) — then the sort falls through
+  // to the hint comparison below.
+  const costKey = (m: RankableModel): number | undefined => {
+    if (typeof m.costOutput === "number" && m.costOutput > 0) return m.costOutput;
+    if (!hasPriceSignal) return undefined;
+    const hint = hintScore(m.spec);
+    return hint > 0 ? max : hint < 0 ? min : median;
+  };
+
+  return models
+    .map((m, index) => ({ m, index, cost: costKey(m), hint: hintScore(m.spec), ctx: m.contextWindow ?? 0 }))
+    .sort((a, b) => {
+      if (a.cost !== undefined && b.cost !== undefined && a.cost !== b.cost) return a.cost - b.cost;
+      if (a.hint !== b.hint) return a.hint - b.hint;
+      if (a.ctx !== b.ctx) return a.ctx - b.ctx;
+      return a.index - b.index;
+    })
+    .map((entry) => entry.m);
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a default tier config. When the available model registry is known,
+ * spread it across tiers so small/medium/big routing is meaningful out of the
+ * box. When the registry is empty or unavailable, fall back to the current Pi
+ * model so fresh installs still get usable tier values.
+ *
+ * Models are first ranked least → most capable via `rankByCapability` (price
+ * first, name-substring hint as fallback). Tiers are then assigned from this
+ * single ranked pool with exclusion — each model is used for at most one tier —
+ * so distinct tiers never collapse onto the same model and a weaker model can
+ * never outrank a stronger one (no inversion):
+ *
+ *   - big    = the most capable model (last in the ranking)
+ *   - small  = the least capable model (first in the ranking)
+ *   - medium = the middle-ranked model
+ *
+ * When fewer than 3 distinct models are available, this degrades gracefully by
+ * reusing the *strongest* available model for the higher tier(s):
+ *
+ *   - 2 models: small = weaker, medium = big = stronger
+ *   - 1 / 0 models: small = medium = big = that model (or the current model /
+ *     "" fallback)
+ *
+ * `availableModels` is injectable for testing and for callers that already
+ * fetched the registry. When omitted, this reads from the live registry.
+ */
+export function buildDefaultTierConfig(
+  currentModelSpec?: string,
+  availableModels?: readonly RankableModel[],
+): ModelTierConfig {
+  const models = availableModels ?? listAvailableModels();
+  const ranked = rankByCapability(models).map((m) => m.spec);
+
+  if (ranked.length >= 3) {
+    const small = ranked[0];
+    const big = ranked[ranked.length - 1];
+    const medium = ranked[Math.floor(ranked.length / 2)];
+    return { tiers: { small, medium, big } };
+  }
+  if (ranked.length === 2) {
+    const [weaker, stronger] = ranked;
+    return { tiers: { small: weaker, medium: stronger, big: stronger } };
+  }
+  const fallback = ranked[0] ?? currentModelSpec ?? "";
+  return {
+    tiers: {
+      small: fallback,
+      medium: fallback,
+      big: fallback,
+    },
+  };
+}
+
+/**
+ * One-time notice shown when an agent requests `opts.tier` but no
+ * model-tiers.json is configured — in that state tiers silently fall back to
+ * the session model (see `resolveAgentModelSpec` in agent.ts), which is easy to
+ * miss. This surfaces the fallback and the mapping the user *would* get by
+ * configuring, using the same `buildDefaultTierConfig` ranking so the hint is
+ * actionable. Pure/string-only so the caller owns how it's emitted.
+ */
+export function formatTierFallbackNotice(
+  mainModel: string | undefined,
+  availableModels: readonly RankableModel[],
+): string {
+  const fallback = mainModel ?? "the session default model";
+  const suggested = buildDefaultTierConfig(mainModel, availableModels);
+  const mapping = sortedTierNames(suggested)
+    .map((tier) => `${tier}=${suggested.tiers[tier] || "?"}`)
+    .join("  ");
+  return (
+    `[workflow] An agent requested opts.tier but no model-tiers.json is configured, so tiers currently ` +
+    `fall back to ${fallback}. Run /workflows-models to configure them` +
+    (mapping ? `. Suggested mapping from your available models: ${mapping}` : ".")
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Load / Save
+// ---------------------------------------------------------------------------
+
+/**
+ * True iff `value` is a usable tiers map: a plain (non-array) object with at
+ * least one entry, every key and value a non-empty string. Anything else
+ * (an array, `{}`, or a tier mapped to `""`) is treated as absent rather than
+ * a truthy-but-broken config — resolveTierModel would silently resolve such
+ * entries to `undefined`/`""` while the caller's "no model-tiers.json
+ * configured" warning only fires on an exactly-null config.
+ */
+function isValidTiersMap(value: unknown): value is Record<string, string> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const entries = Object.entries(value as Record<string, unknown>);
+  if (entries.length === 0) return false;
+  return entries.every(([key, val]) => key.trim().length > 0 && typeof val === "string" && val.trim().length > 0);
+}
+
+/**
+ * Load the model tier config from disk. Returns null if the file does not
+ * exist or is unparseable (callers fall back to a default).
+ */
+export function loadModelTierConfig(configPath?: string): ModelTierConfig | null {
+  const path = configPath ?? getModelTierConfigPath();
+  if (!existsSync(path)) return null;
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") return null;
+    if (!isValidTiersMap(parsed.tiers)) return null;
+    return parsed as ModelTierConfig;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save a model tier config to disk. Creates parent directories if needed.
+ *
+ * Refuses a degenerate `tiers` (e.g. all-empty-string, from buildDefaultTierConfig
+ * with an empty model registry) using the same isValidTiersMap check the loader
+ * uses — otherwise the write side could produce exactly the shape loadModelTierConfig
+ * now rejects on the next read, silently discarding the "saved" config.
+ */
+export function saveModelTierConfig(config: ModelTierConfig, configPath?: string): void {
+  if (!isValidTiersMap(config?.tiers)) {
+    throw new Error(
+      "Refusing to save a degenerate model tier config: tiers must be a non-empty map of tier name to a non-empty model spec string.",
+    );
+  }
+  const path = configPath ?? getModelTierConfigPath();
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(config, null, 2), "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Resolve / helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve a tier name to its configured model spec, or undefined if the tier
+ * is not configured.
+ */
+export function resolveTierModel(tier: string, config: ModelTierConfig): string | undefined {
+  return config.tiers[tier];
+}
+
+/** Return all tier names sorted: small < medium < big, then alphabetically. */
+export function sortedTierNames(config: ModelTierConfig): string[] {
+  const names = Object.keys(config.tiers);
+  const rank: Record<string, number> = { small: 0, medium: 1, big: 2 };
+  return names.sort((a, b) => (rank[a] ?? 99) - (rank[b] ?? 99) || a.localeCompare(b));
+}