@underactive/pi-topping-moa-fusion 0.1.0

package/src/agents/defaults.ts

@@ -0,0 +1,123 @@
+/**
+ * Default model/thinking selections for the user-customizable planning
+ * subagents, stored in the frontmatter of the installed agent files.
+ *
+ * The installed copies under `~/.pi/agent/agents/` are authoritative at
+ * runtime, so writes target those rather than this package's shipped `agents/`
+ * directory (which only seeds them, no-clobber, via installShippedAgents).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { isThinkingLevel, type ThinkingLevel } from "../shared/modelRefs.ts";
+
+export interface ConfigurableAgent {
+	name: string;
+	menuLabel: string;
+	title: string;
+	description: string;
+}
+
+/**
+ * The shipped agents whose model the user may choose. `moa-proposer` and
+ * `moa-synthesizer` are excluded: their model is assigned per slot at runtime,
+ * and withAuthoritativeMoaAgents replaces their on-disk copies wholesale, so
+ * any frontmatter written to them would be ignored. `mf-plan` is excluded
+ * too: it follows the session model chosen when entering plan mode, so a
+ * configured default would never be read.
+ */
+export const CONFIGURABLE_AGENTS: readonly ConfigurableAgent[] = [
+	{
+		name: "moa-explore",
+		menuLabel: "explore agent",
+		title: "Explore agent — fast codebase recon",
+		description: "Runs high-volume file reads and greps to gather context before planning. Favor a fast, inexpensive model: this role needs breadth and speed, not deep reasoning.",
+	},
+];
+
+export interface AgentFrontmatterDefault {
+	/** Raw frontmatter value — shipped defaults are bare ids (`claude-haiku-4-5`), not `provider/id`. */
+	model?: string;
+	thinking?: ThinkingLevel;
+}
+
+export function installedAgentPath(name: string): string {
+	return path.join(getAgentDir(), "agents", `${name}.md`);
+}
+
+/** Index of the closing `---` of a leading frontmatter block, or -1 if there is none. */
+function frontmatterEnd(lines: string[]): number {
+	if (lines[0]?.trim() !== "---") return -1;
+	for (let index = 1; index < lines.length; index++) {
+		if (lines[index]?.trim() === "---") return index;
+	}
+	return -1;
+}
+
+/** The value of `line` if it assigns `key`, else undefined. */
+function readField(line: string, key: string): string | undefined {
+	const match = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+	if (!match || match[1] !== key) return undefined;
+	return match[2]!.trim();
+}
+
+function setField(frontmatterLines: string[], key: string, value: string): void {
+	const index = frontmatterLines.findIndex((line) => readField(line, key) !== undefined);
+	if (index >= 0) frontmatterLines[index] = `${key}: ${value}`;
+	else frontmatterLines.push(`${key}: ${value}`);
+}
+
+export function readAgentDefault(name: string): AgentFrontmatterDefault {
+	let content: string;
+	try {
+		content = fs.readFileSync(installedAgentPath(name), "utf-8");
+	} catch {
+		return {};
+	}
+
+	const lines = content.split("\n");
+	const end = frontmatterEnd(lines);
+	if (end < 0) return {};
+
+	const result: AgentFrontmatterDefault = {};
+	for (let index = 1; index < end; index++) {
+		const line = lines[index]!;
+		const model = readField(line, "model");
+		if (model) result.model = model;
+		const thinking = readField(line, "thinking");
+		if (thinking && isThinkingLevel(thinking)) result.thinking = thinking;
+	}
+	return result;
+}
+
+/**
+ * Rewrite just the `model:`/`thinking:` lines of an installed agent's
+ * frontmatter, leaving every other line — including the prompt body and any
+ * hand-added keys — byte-for-byte intact. Returns false when the file is
+ * missing or carries no frontmatter block.
+ */
+export function writeAgentDefault(name: string, model: string, thinking: ThinkingLevel): boolean {
+	const filePath = installedAgentPath(name);
+	let content: string;
+	try {
+		content = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return false;
+	}
+
+	const lines = content.split("\n");
+	const end = frontmatterEnd(lines);
+	if (end < 0) return false;
+
+	const frontmatterLines = lines.slice(1, end);
+	setField(frontmatterLines, "model", model);
+	setField(frontmatterLines, "thinking", thinking);
+
+	try {
+		fs.writeFileSync(filePath, [lines[0]!, ...frontmatterLines, ...lines.slice(end)].join("\n"), "utf-8");
+	} catch {
+		return false;
+	}
+	return true;
+}

package/src/agents/discovery.ts

@@ -0,0 +1,119 @@
+/**
+ * Agent discovery and configuration.
+ * Ported from pi's subagent example agents.ts.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { isThinkingLevel, type ThinkingLevel } from "../shared/modelRefs.ts";
+
+export type AgentScope = "user" | "project" | "both";
+
+export interface AgentConfig {
+	name: string;
+	description: string;
+	tools?: string[];
+	model?: string;
+	thinking?: ThinkingLevel;
+	systemPrompt: string;
+	source: "user" | "project";
+	filePath: string;
+}
+
+export interface AgentDiscoveryResult {
+	agents: AgentConfig[];
+	projectAgentsDir: string | null;
+}
+
+/** Parse a single agent markdown file into an `AgentConfig`, or `undefined` if malformed/unreadable. */
+export function parseAgentFile(filePath: string, source: "user" | "project"): AgentConfig | undefined {
+	let content: string;
+	try {
+		content = fs.readFileSync(filePath, "utf-8");
+	} catch {
+		return undefined;
+	}
+
+	const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+
+	if (!frontmatter.name || !frontmatter.description) return undefined;
+
+	const tools = frontmatter.tools
+		?.split(",")
+		.map((t: string) => t.trim())
+		.filter(Boolean);
+
+	// An unrecognized level is dropped rather than forwarded: `--thinking` on the
+	// child process would reject it and fail the whole agent run.
+	const thinking = frontmatter.thinking?.trim();
+
+	return {
+		name: frontmatter.name,
+		description: frontmatter.description,
+		tools: tools && tools.length > 0 ? tools : undefined,
+		model: frontmatter.model,
+		thinking: thinking && isThinkingLevel(thinking) ? thinking : undefined,
+		systemPrompt: body,
+		source,
+		filePath,
+	};
+}
+
+function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig[] {
+	const agents: AgentConfig[] = [];
+
+	if (!fs.existsSync(dir)) return agents;
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return agents;
+	}
+
+	for (const entry of entries) {
+		if (!entry.name.endsWith(".md")) continue;
+		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
+
+		const agent = parseAgentFile(path.join(dir, entry.name), source);
+		if (agent) agents.push(agent);
+	}
+
+	return agents;
+}
+
+function isDirectory(p: string): boolean {
+	try {
+		return fs.statSync(p).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+function findNearestProjectAgentsDir(cwd: string): string | null {
+	let currentDir = cwd;
+	while (true) {
+		const candidate = path.join(currentDir, CONFIG_DIR_NAME, "agents");
+		if (isDirectory(candidate)) return candidate;
+
+		const parentDir = path.dirname(currentDir);
+		if (parentDir === currentDir) return null;
+		currentDir = parentDir;
+	}
+}
+
+export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
+	const userDir = path.join(getAgentDir(), "agents");
+	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
+
+	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
+
+	const agentMap = new Map<string, AgentConfig>();
+
+	for (const agent of userAgents) agentMap.set(agent.name, agent);
+	for (const agent of projectAgents) agentMap.set(agent.name, agent);
+
+	return { agents: Array.from(agentMap.values()), projectAgentsDir };
+}

package/src/config/modelCatalogue.ts

@@ -0,0 +1,54 @@
+/**
+ * Cached view of the models pi reports as usable, with the thinking levels the
+ * registry declares for each.
+ *
+ * The registry is the only authority the pickers consult: it decides both which
+ * models may be selected and which thinking levels each one supports, so a
+ * confirmed selection needs no further verification. Whether a model actually
+ * answers is decided when it runs, not here.
+ */
+
+import { getSupportedThinkingLevels, type Api, type Model } from "@earendil-works/pi-ai";
+import { isThinkingLevel, modelRefLabel, parseRef, type ModelRef, type ThinkingLevel } from "../shared/modelRefs.ts";
+
+export interface ModelCatalogue {
+	/** Selectable models, sorted by `provider/id`. */
+	availableRefs(): ModelRef[];
+	/** Levels the registry declares for a model, in pi's canonical order. */
+	thinkingLevelsFor(ref: ModelRef): ThinkingLevel[];
+}
+
+/** The slice of pi's `ModelRegistry` a catalogue is built from. */
+export interface CatalogueRegistry {
+	getAvailable(): Model<Api>[];
+}
+
+// Lives for as long as the registry object itself: pi hands extensions a stable
+// registry per session, and dropping the registry drops its catalogue with it.
+const CATALOGUES = new WeakMap<CatalogueRegistry, ModelCatalogue>();
+
+export function getModelCatalogue(registry: CatalogueRegistry): ModelCatalogue {
+	const cached = CATALOGUES.get(registry);
+	if (cached) return cached;
+	const built = buildCatalogue(registry);
+	CATALOGUES.set(registry, built);
+	return built;
+}
+
+function buildCatalogue(registry: CatalogueRegistry): ModelCatalogue {
+	const levels = new Map<string, ThinkingLevel[]>();
+	for (const model of registry.getAvailable()) {
+		const key = `${model.provider}/${model.id}`;
+		if (levels.has(key)) continue;
+		levels.set(key, getSupportedThinkingLevels(model).filter(isThinkingLevel));
+	}
+
+	const refs = [...levels.keys()]
+		.sort((a, b) => a.localeCompare(b))
+		.map((key) => parseRef(key));
+
+	return {
+		availableRefs: () => [...refs],
+		thinkingLevelsFor: (ref) => levels.get(modelRefLabel(ref)) ?? [],
+	};
+}

package/src/config/planName.ts

@@ -0,0 +1,74 @@
+/**
+ * LLM-based 4-word plan name generation for repo-local plan files.
+ */
+
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadMoaConfig } from "./settings.ts";
+import { fallbackPlanName, generateWordSlug, trySlugifyPlanName } from "../planning/planFile.ts";
+
+function buildSummarizePrompt(prompt: string): string {
+	return [
+		"Summarize the following planning request in exactly 4 words.",
+		"Reply with ONLY those 4 words separated by spaces, no punctuation, all lowercase.",
+		"",
+		"<request>",
+		prompt,
+		"</request>",
+	].join("\n");
+}
+
+/** Call the active model to summarize a plan prompt into a 4-word slug. */
+export async function summarizePlanPromptName(ctx: ExtensionContext, prompt: string): Promise<string> {
+	const promptSlug = trySlugifyPlanName(prompt);
+	const fallback = () => promptSlug ?? fallbackPlanName();
+
+	const config = loadMoaConfig();
+
+	// When summary names are disabled, use a random adjective-adjective-noun phrase directly.
+	if (!config.useSummaryName) return generateWordSlug();
+
+	const cheapRef = config.cheap;
+	const model = cheapRef
+		? ctx.modelRegistry.find(cheapRef.provider, cheapRef.id) ?? ctx.model
+		: ctx.model;
+	if (!model) return fallback();
+
+	const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	if (!auth?.ok || !auth.apiKey) return fallback();
+
+	try {
+		// Naming a plan file is not a reasoning task, and the cheap/fast model is
+		// chosen to be cheap. Omitting `reasoning` is how pi's simple-stream API
+		// spells "thinking off" (its ThinkingLevel type has no "off" member), so
+		// providers send their disabled-reasoning mapping rather than a default.
+		const response = await completeSimple(
+			model,
+			{
+				messages: [
+					{
+						role: "user",
+						content: [{ type: "text", text: buildSummarizePrompt(prompt) }],
+						timestamp: Date.now(),
+					},
+				],
+			},
+			{
+				apiKey: auth.apiKey,
+				headers: auth.headers,
+				env: auth.env,
+			},
+		);
+
+		const text = response.content
+			.filter((part): part is { type: "text"; text: string } => part.type === "text")
+			.map((part) => part.text)
+			.join("")
+			.trim();
+
+		const slug = trySlugifyPlanName(text);
+		return slug ?? fallback();
+	} catch {
+		return fallback();
+	}
+}

package/src/config/rosters.ts

@@ -0,0 +1,118 @@
+/**
+ * Named agent rosters for MoA plan runs.
+ *
+ * A roster bundles one model + thinking level for every fan-out role — up to
+ * five proposers plus synthesizer, implementer, and verifier — so a whole
+ * assignment set can be reused across runs and loaded wholesale from the
+ * picker's "Load Roster" row. Rosters are defined in `/mf-plan-settings` and
+ * persisted in settings.json; they are pure data here: nothing in this module
+ * consults the model registry, so an unavailable provider must never erase a
+ * saved definition. Availability is filtered where rosters are applied.
+ *
+ * Pure module — no I/O — so tests need none.
+ */
+
+import { isModelRef, isThinkingLevel, shortModelName, type ModelRef, type ThinkingLevel } from "../shared/modelRefs.ts";
+
+export const MIN_ROSTER_PROPOSERS = 2;
+export const MAX_ROSTER_PROPOSERS = 5;
+export const MAX_ROSTER_NAME_LENGTH = 24;
+export const MAX_ROSTER_COUNT = 20;
+export const ROSTER_NAME_PATTERN = /^[A-Za-z0-9]+$/;
+
+/** One model + thinking level assignment for a single role slot. */
+export interface RosterSlot {
+	ref: ModelRef;
+	thinking: ThinkingLevel;
+}
+
+/** A complete saved team: a dense slot-ordered proposer list plus the three required roles. */
+export interface PlanRoster {
+	name: string;
+	/** Dense in slot order, `MIN_ROSTER_PROPOSERS..MAX_ROSTER_PROPOSERS` entries. */
+	proposers: RosterSlot[];
+	synthesizer: RosterSlot;
+	implementer: RosterSlot;
+	verifier: RosterSlot;
+}
+
+/** An in-progress roster in the editor: proposer slots may be empty and required roles unset. */
+export interface DraftRoster {
+	name: string;
+	/** Fixed `MAX_ROSTER_PROPOSERS` length; `undefined` entries are unassigned. */
+	proposers: (RosterSlot | undefined)[];
+	synthesizer?: RosterSlot;
+	implementer?: RosterSlot;
+	verifier?: RosterSlot;
+}
+
+export function isRosterSlot(value: unknown): value is RosterSlot {
+	return !!value
+		&& typeof value === "object"
+		&& isModelRef((value as RosterSlot).ref)
+		&& typeof (value as RosterSlot).thinking === "string"
+		&& isThinkingLevel((value as RosterSlot).thinking);
+}
+
+/** Sanitise a parsed `rosters` array the way persona-audit does its rosters. */
+export function parseRosters(value: unknown): PlanRoster[] {
+	const rosters: PlanRoster[] = [];
+	const names = new Set<string>();
+	if (!Array.isArray(value)) return rosters;
+	for (const entry of value) {
+		if (rosters.length >= MAX_ROSTER_COUNT) break;
+		if (!entry || typeof entry !== "object") continue;
+		const candidate = entry as Partial<PlanRoster>;
+		if (typeof candidate.name !== "string" || !Array.isArray(candidate.proposers)) continue;
+		const name = candidate.name.trim();
+		const normalizedName = name.toLowerCase();
+		if (
+			name.length < 1
+			|| name.length > MAX_ROSTER_NAME_LENGTH
+			|| !ROSTER_NAME_PATTERN.test(name)
+			|| names.has(normalizedName)
+		) continue;
+		if (!isRosterSlot(candidate.synthesizer) || !isRosterSlot(candidate.implementer) || !isRosterSlot(candidate.verifier)) continue;
+
+		const proposers: RosterSlot[] = [];
+		for (const slot of candidate.proposers) {
+			if (isRosterSlot(slot)) proposers.push(slot);
+			if (proposers.length >= MAX_ROSTER_PROPOSERS) break;
+		}
+		if (proposers.length < MIN_ROSTER_PROPOSERS) continue;
+		names.add(normalizedName);
+		rosters.push({ name, proposers, synthesizer: candidate.synthesizer, implementer: candidate.implementer, verifier: candidate.verifier });
+	}
+	return rosters;
+}
+
+/** Validation message for a prospective roster name, or undefined when acceptable. */
+export function rosterNameError(name: string, rosters: { name: string }[], currentIndex?: number): string | undefined {
+	if (name.length < 1 || name.length > MAX_ROSTER_NAME_LENGTH || !ROSTER_NAME_PATTERN.test(name)) {
+		return `Roster names must be 1–${MAX_ROSTER_NAME_LENGTH} alphanumeric characters.`;
+	}
+	if (rosters.some((roster, index) => index !== currentIndex && roster.name.toLowerCase() === name.toLowerCase())) {
+		return `A roster named ${name} already exists.`;
+	}
+	return undefined;
+}
+
+/** Compact one-line summary of a roster's models, e.g. "P: opus, haiku · S: opus · I: opus · V: haiku". */
+export function rosterSummary(roster: PlanRoster): string {
+	const proposers = roster.proposers.map((slot) => shortModelName(slot.ref)).join(", ");
+	return `P: ${proposers} · S: ${shortModelName(roster.synthesizer.ref)} · I: ${shortModelName(roster.implementer.ref)} · V: ${shortModelName(roster.verifier.ref)}`;
+}
+
+/** What a draft is still missing before it can be saved, or undefined when complete. */
+export function rosterReadinessError(draft: DraftRoster): string | undefined {
+	const assigned = draft.proposers.filter((slot) => slot !== undefined).length;
+	const missing: string[] = [];
+	const shortfall = MIN_ROSTER_PROPOSERS - assigned;
+	if (shortfall > 0) missing.push(shortfall === 1 ? "1 more proposer" : `${shortfall} proposers`);
+	if (!draft.synthesizer) missing.push("a synthesizer");
+	if (!draft.implementer) missing.push("an implementer");
+	if (!draft.verifier) missing.push("a verifier");
+	if (missing.length === 0) return undefined;
+	if (missing.length === 1) return `A roster needs ${missing[0]}.`;
+	return `A roster needs ${missing.slice(0, -1).join(", ")} and ${missing[missing.length - 1]}.`;
+}

package/src/config/settings.ts

@@ -0,0 +1,161 @@
+/**
+ * MoA (Mixture-of-Agents) configuration for /mf-plan.
+ *
+ * Persists the last-used mode + model selections so the picker can
+ * pre-fill/remember choices across sessions. Purely a UI convenience — the
+ * picker is always shown after a plan prompt is submitted, this file never
+ * causes it to be skipped.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+	THINKING_LEVELS,
+	isModelRef,
+	isThinkingLevel,
+	type ModelRef,
+	type ThinkingLevel,
+} from "../shared/modelRefs.ts";
+import { parseRosters, type PlanRoster } from "./rosters.ts";
+
+export type MoaMode = "single" | "moa";
+
+export interface MoaConfig {
+	mode: MoaMode;
+	proposers: ModelRef[];
+	opinionModels: ModelRef[];
+	debateModels: ModelRef[];
+	/** Round ceiling for /mf-debate, clamped to the picker's 2–5 range. */
+	debateRounds: number;
+	synthesizer?: ModelRef;
+	implementer?: ModelRef;
+	verifier?: ModelRef;
+	cheap?: ModelRef;
+	/** Last thinking level chosen for a model in the picker, keyed by `modelRefLabel(ref)`. */
+	thinkingOverrides: Record<string, ThinkingLevel>;
+	/** Named model+thinking rosters loadable wholesale from the picker's Load Roster row. */
+	rosters: PlanRoster[];
+	/** Auto-accept recommended conflict resolutions without showing the TUI conflict overlay. */
+	autoResolveConflicts: boolean;
+	/** Use LLM-summarized plan names (true) or random adjective-adjective-noun phrases (false). */
+	useSummaryName: boolean;
+	/**
+	 * Whether the user has been through the setup overlay at least once. Gates the
+	 * first `/mf-plan` into setup. Kept here rather than inferred from the agent
+	 * files because those always carry a shipped `model:`, so their contents cannot
+	 * distinguish a shipped default from a deliberate choice.
+	 */
+	agentDefaultsConfigured: boolean;
+}
+
+function emptyConfig(): MoaConfig {
+	return {
+		mode: "single",
+		proposers: [],
+		opinionModels: [],
+		debateModels: [],
+		debateRounds: 3,
+		synthesizer: undefined,
+		implementer: undefined,
+		verifier: undefined,
+		cheap: undefined,
+		thinkingOverrides: {},
+		rosters: [],
+		autoResolveConflicts: false,
+		useSummaryName: true,
+		agentDefaultsConfigured: false,
+	};
+}
+
+/** Persistent MoA settings, colocated with pi's user-level settings rather than generated plans. */
+export function moaSettingsPath(): string {
+	return join(getAgentDir(), "mf-plan", "settings.json");
+}
+
+function parseSettingsFile(path: string): MoaConfig {
+	try {
+		const raw = readFileSync(path, "utf-8");
+		const parsed = JSON.parse(raw) as Partial<MoaConfig>;
+		const proposers = Array.isArray(parsed.proposers)
+			? parsed.proposers.filter(isModelRef)
+			: [];
+		const opinionModels = Array.isArray(parsed.opinionModels)
+			? parsed.opinionModels.filter(isModelRef)
+			: [];
+		const debateModels = Array.isArray(parsed.debateModels)
+			? parsed.debateModels.filter(isModelRef)
+			: [];
+		const debateRounds = typeof parsed.debateRounds === "number" && Number.isFinite(parsed.debateRounds)
+			? Math.min(5, Math.max(2, Math.round(parsed.debateRounds)))
+			: 3;
+		const synthesizer = isModelRef(parsed.synthesizer) ? parsed.synthesizer : undefined;
+		const implementer = isModelRef(parsed.implementer) ? parsed.implementer : undefined;
+		const verifier = isModelRef(parsed.verifier) ? parsed.verifier : undefined;
+		const cheap = isModelRef(parsed.cheap) ? parsed.cheap : undefined;
+		const mode: MoaMode = parsed.mode === "moa" ? "moa" : "single";
+
+		const thinkingOverrides: Record<string, ThinkingLevel> = {};
+		if (parsed.thinkingOverrides && typeof parsed.thinkingOverrides === "object") {
+			for (const [key, value] of Object.entries(parsed.thinkingOverrides)) {
+				if (typeof value === "string" && isThinkingLevel(value)) thinkingOverrides[key] = value;
+			}
+		}
+
+		const autoResolveConflicts = typeof parsed.autoResolveConflicts === "boolean"
+			? parsed.autoResolveConflicts
+			: false;
+
+		const useSummaryName = typeof parsed.useSummaryName === "boolean"
+			? parsed.useSummaryName
+			: true;
+
+		const agentDefaultsConfigured = parsed.agentDefaultsConfigured === true;
+		const rosters = parseRosters(parsed.rosters);
+
+		return { mode, proposers, opinionModels, debateModels, debateRounds, synthesizer, implementer, verifier, cheap, thinkingOverrides, rosters, autoResolveConflicts, useSummaryName, agentDefaultsConfigured };
+	} catch (err) {
+		console.error("mf-plan: failed to parse settings, using defaults:", err);
+		return emptyConfig();
+	}
+}
+
+export function loadMoaConfig(): MoaConfig {
+	const settingsPath = moaSettingsPath();
+	if (existsSync(settingsPath)) return parseSettingsFile(settingsPath);
+	return emptyConfig();
+}
+
+export function saveMoaConfig(config: MoaConfig): void {
+	const path = moaSettingsPath();
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, `${JSON.stringify(config, null, "\t")}\n`, "utf-8");
+}
+
+export function moaSettingsExist(): boolean {
+	return existsSync(moaSettingsPath());
+}
+
+/**
+ * The levels to offer for a model, in pi's canonical thinking-level order.
+ * The registry's declared range is the whole answer — a level it does not list
+ * is one the backend will refuse.
+ */
+export function thinkingOptionsForModel(registryLevels: ThinkingLevel[]): ThinkingLevel[] {
+	return THINKING_LEVELS.filter((level) => registryLevels.includes(level));
+}
+
+/** Selects a model's saved level, the current level, or a sensible default in that order. */
+export function defaultThinkingForModel(
+	key: string,
+	config: MoaConfig,
+	currentLevel: ThinkingLevel,
+	registryLevels: ThinkingLevel[],
+): ThinkingLevel {
+	const options = thinkingOptionsForModel(registryLevels);
+	const saved = config.thinkingOverrides[key];
+	if (saved && options.includes(saved)) return saved;
+	if (options.includes(currentLevel)) return currentLevel;
+	if (options.includes("medium")) return "medium";
+	return options[0] ?? "medium";
+}