pi-better-model-select 0.1.3 → 0.2.0

package/extensions/lib/agents.ts

@@ -0,0 +1,60 @@
+// Optional, isolated adapter: pi-subagents currently has no public discovery RPC.
+// Never vendor a second agent-discovery implementation or execute an agent to list roles.
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface AgentRole {
+  name: string;
+  model?: string;
+  thinking?: string | false;
+  runner?: unknown;
+  source?: string;
+  modelSource?: unknown;
+}
+export interface AgentDiscovery {
+  roles: AgentRole[];
+  projectRoot: string;
+  warning?: string;
+}
+/** Resolve the owning package, not the directory of its possibly bundled entry point. */
+export function subagentsPackageRoot(entry: string): string {
+  let directory = dirname(entry);
+  for (;;) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(directory, "package.json"), "utf8"));
+      if (manifest.name === "pi-subagents") return directory;
+    } catch { /* keep looking above a bundle or other entry-point directory */ }
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error("Cannot locate pi-subagents package root");
+    directory = parent;
+  }
+}
+export async function discoverRoles(cwd: string, pi: any, provider?: string, trusted = false): Promise<AgentDiscovery> {
+  try {
+    // Resolve only from this extension or the user's trusted Pi package directory.
+    const roots = [import.meta.url, pathToFileURL(join(getAgentDir(), "npm", "package.json")).href];
+    let entry: string | undefined;
+    for (const root of roots) {
+      try { entry = createRequire(root).resolve("pi-subagents"); break; } catch { /* optional package */ }
+    }
+    if (!entry) throw new Error("pi-subagents is not resolvable from BMS or the Pi npm package directory");
+    const base = subagentsPackageRoot(entry);
+    const api = await import(pathToFileURL(join(base, "src/agents/agents.js")).href);
+    if (typeof api.discoverAgents !== "function") throw new Error("Unsupported pi-subagents discovery API");
+    api.clearAgentDiscoveryCache?.();
+    const result = api.discoverAgents(cwd, trusted ? "both" : "user", provider, { projectTrusted: trusted });
+    let roles: AgentRole[] = result.agents;
+    try {
+      const runtime = await import(pathToFileURL(join(base, "src/agents/runtime-agent-registry.js")).href);
+      roles = runtime.mergeRuntimeAgents(pi, result, undefined, { cwd, scope: trusted ? "both" : "user", preferredModelProvider: provider, projectTrusted: trusted }).agents;
+    } catch { /* older versions have filesystem agents only */ }
+    // Native Pi and subagents may choose different roots. Use the subagents settings root for agents.
+    const projectRoot = api.findConfiguredProjectRoot?.(cwd) ?? cwd;
+    return { roles: [...roles].sort((a, b) => a.name.localeCompare(b.name)), projectRoot };
+  } catch (error) {
+    return { roles: [], projectRoot: cwd, warning: `Agent discovery unavailable: ${error}. Pi defaults remain available.` };
+  }
+}

package/extensions/lib/defaults-models.ts

@@ -0,0 +1,15 @@
+import { rankModels, type RankedModel } from "./picker.ts";
+import type { ModelsConfig } from "./store.ts";
+
+/** Assignment menus include authenticated registry models, not only custom models.json entries. */
+export function rankModelsForDefaults(config: ModelsConfig, ctx: any): RankedModel[] {
+  const rows = rankModels(config);
+  const seen = new Set(rows.map(row => `${row.provider}/${row.modelId}`));
+  for (const model of ctx.modelRegistry.getAvailable?.() ?? []) {
+    const key = `${model.provider}/${model.id}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    rows.push({ provider: model.provider, modelId: model.id, label: model.name ?? model.id, count: 0, lastUsed: 0, reasoning: model.reasoning, contextWindow: model.contextWindow });
+  }
+  return rows;
+}

package/extensions/lib/defaults-store.ts

@@ -0,0 +1,108 @@
+// Defaults use native Pi settings. BMS capability hints live separately from models.json.
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { randomUUID } from "node:crypto";
+
+export const EFFORTS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export type Effort = typeof EFFORTS[number];
+export type Scope = "user" | "project";
+export type JsonObject = Record<string, any>;
+export function isEffort(value: unknown): value is Effort {
+  return typeof value === "string" && (EFFORTS as readonly string[]).includes(value);
+}
+export function object(value: unknown): JsonObject {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Expected a JSON object");
+  return value as JsonObject;
+}
+export function readSettings(path: string): JsonObject {
+  if (!existsSync(path)) return {};
+  return object(JSON.parse(readFileSync(path, "utf8")));
+}
+/** Fail closed on malformed files; serialize BMS writers and re-read immediately before patching. */
+export function patchSettings(path: string, patch: (settings: JsonObject) => void): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = `${path}.bms-lock`;
+  const fd = openSync(lock, "wx", 0o600);
+  const tmp = `${path}.bms-${randomUUID()}`;
+  try {
+    const settings = readSettings(path);
+    patch(settings);
+    writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n", { mode: 0o600 });
+    renameSync(tmp, path);
+  } finally {
+    if (existsSync(tmp)) unlinkSync(tmp);
+    closeSync(fd);
+    unlinkSync(lock);
+  }
+}
+export function settingsPath(cwd: string, scope: Scope, agentDir = getAgentDir()): string {
+  return scope === "user" ? join(agentDir, "settings.json") : join(cwd, ".pi", "settings.json");
+}
+export interface Capability {
+  levels: Effort[];
+  source: "provider" | "manual" | "pi";
+}
+export function metadataPath(): string { return join(getAgentDir(), "bms-model-metadata.json"); }
+export function normalizeEfforts(raw: unknown): Effort[] | undefined {
+  if (!Array.isArray(raw) || !raw.length || !raw.every(isEffort)) return undefined;
+  return EFFORTS.filter(level => raw.includes(level));
+}
+export function capabilities(key: string, model?: { reasoning?: boolean; thinkingLevelMap?: Record<string, unknown> }, path = metadataPath()): { levels: Effort[]; source: string } {
+  const stored = readSettings(path)[key];
+  const levels = normalizeEfforts(stored?.levels);
+  if (levels) return { levels, source: stored.source === "provider" ? "Provider metadata" : stored.source === "manual" ? "Manual override" : "Pi standard levels; provider support unverified" };
+  if (model?.reasoning === false) return { levels: ["off"], source: "Non-reasoning model" };
+  // Native maps explicitly mark unsupported Pi levels with null.
+  if (model?.thinkingLevelMap) {
+    const supported = EFFORTS.filter(level => model.thinkingLevelMap![level] !== null);
+    if (supported.length) return { levels: supported, source: "Pi model capability map" };
+  }
+  return { levels: [...EFFORTS], source: "Pi standard levels; provider support unverified" };
+}
+export function saveCapability(key: string, capability: Capability, path = metadataPath()): void {
+  if (!normalizeEfforts(capability.levels)) throw new Error("Choose at least one valid effort level");
+  patchSettings(path, data => { data[key] = capability; });
+}
+export function setPiDefault(data: JsonObject, provider: string, model: string, effort: Effort | undefined): void {
+  data.defaultProvider = provider;
+  data.defaultModel = model;
+  if (effort === undefined) delete data.defaultThinkingLevel;
+  else data.defaultThinkingLevel = effort;
+  // A per-model startup preference would otherwise beat the newly chosen default.
+  if (data.modelThinkingLevels !== undefined) {
+    const levels = object(data.modelThinkingLevels);
+    delete levels[`${provider}/${model}`];
+  }
+}
+export function setRoleField(data: JsonObject, role: string | undefined, field: "model" | "thinking", value: string | false | undefined): void {
+  if (role && ["__proto__", "constructor", "prototype"].includes(role)) throw new Error("Invalid agent name");
+  const sub = data.subagents === undefined ? data.subagents = {} : object(data.subagents);
+  if (!role) {
+    const key = field === "model" ? "defaultModel" : "defaultThinking";
+    if (value === undefined) delete sub[key];
+    else sub[key] = value;
+    return;
+  }
+  const overrides = sub.agentOverrides === undefined ? sub.agentOverrides = {} : object(sub.agentOverrides);
+  const entry = Object.hasOwn(overrides, role) ? object(overrides[role]) : overrides[role] = {};
+  if (value === undefined) delete entry[field];
+  else entry[field] = value;
+  if (!Object.keys(entry).length) delete overrides[role];
+}
+/** Settings-only projection for the menu, not a claim about a running child. */
+export function roleField(user: JsonObject, project: JsonObject, provider: string | undefined, role: string | undefined, field: "model" | "thinking"): { value: unknown; source: string } {
+  for (const [scope, data] of [["Project", project], ["User", user]] as const) {
+    const sub = data.subagents;
+    if (role) {
+      const scoped = provider && sub?.agentOverridesByProvider?.[provider]?.[role];
+      if (scoped && Object.hasOwn(scoped, field)) return { value: scoped[field], source: `${scope}, provider override` };
+      const regular = sub?.agentOverrides?.[role];
+      if (regular && Object.hasOwn(regular, field)) return { value: regular[field], source: `${scope} role override` };
+    } else {
+      const key = field === "model" ? "defaultModel" : "defaultThinking";
+      if (sub && Object.hasOwn(sub, key)) return { value: sub[key], source: `${scope} fallback` };
+    }
+  }
+  return { value: undefined, source: role ? "Agent-defined / fallback" : "Parent session" };
+}

package/extensions/lib/defaults.ts

@@ -0,0 +1,149 @@
+import { discoverRoles, type AgentRole } from "./agents.ts";
+import { capabilities, isEffort, patchSettings, readSettings, roleField, setPiDefault, setRoleField, settingsPath, type Effort, type JsonObject, type Scope } from "./defaults-store.ts";
+import { pickerDialog } from "./picker-dialog.ts";
+import { rankModelsForDefaults } from "./defaults-models.ts";
+import type { ModelsConfig } from "./store.ts";
+
+export async function chooseEffort(ctx: any, key: string, model?: any, initial?: unknown): Promise<Effort | "automatic" | undefined> {
+  const capability = capabilities(key, model);
+  const levels = [...capability.levels];
+  if (isEffort(initial) && levels.includes(initial)) levels.splice(levels.indexOf(initial), 1), levels.unshift(initial);
+  return ctx.ui.select(`Effort for ${key}\n${capability.source}\nAutomatic removes this scope's preference. Pi/provider may clamp unsupported levels.`, ["automatic", ...levels]);
+}
+export function piPreference(user: JsonObject, project: JsonObject): { provider?: string; model?: string; effort?: Effort; source: string } {
+  const provider = project.defaultProvider ?? user.defaultProvider;
+  const model = project.defaultModel ?? user.defaultModel;
+  const key = `${provider}/${model}`;
+  const effort = project.modelThinkingLevels?.[key] ?? user.modelThinkingLevels?.[key] ?? project.defaultThinkingLevel ?? user.defaultThinkingLevel;
+  return { provider, model, effort, source: project.defaultModel !== undefined || project.defaultProvider !== undefined ? "Project" : "User / automatic" };
+}
+function trusted(pi: any, ctx: any): boolean {
+  return typeof ctx.isProjectTrusted === "function" ? ctx.isProjectTrusted() : typeof pi.isProjectTrusted === "function" && pi.isProjectTrusted();
+}
+function projectSettings(pi: any, ctx: any, cwd: string): JsonObject { return trusted(pi, ctx) ? readSettings(settingsPath(cwd, "project")) : {}; }
+
+/** Switch first; never replace saved defaults when authentication/model selection fails. */
+export async function setMainDefault(pi: any, ctx: any, provider: string, modelId: string, scope: Scope = "user"): Promise<void> {
+  if (scope === "project" && !trusted(pi, ctx)) throw new Error("Project is not trusted");
+  await ctx.modelRegistry.refresh();
+  const model = ctx.modelRegistry.find(provider, modelId);
+  if (!model) throw new Error(`Model ${provider}/${modelId} is not in the active registry`);
+  const user = readSettings(settingsPath(ctx.cwd, "user"));
+  const project = projectSettings(pi, ctx, ctx.cwd);
+  const choice = await chooseEffort(ctx, `${provider}/${modelId}`, model, piPreference(user, project).effort);
+  if (choice === undefined) return;
+  const effort = choice === "automatic" ? undefined : choice;
+  const preview = structuredClone(scope === "user" ? user : project);
+  setPiDefault(preview, provider, modelId, effort);
+  const effective = piPreference(scope === "user" ? preview : user, scope === "project" ? preview : project);
+  const shadowed = effective.provider !== provider || effective.model !== modelId || (effort !== undefined && effective.effort !== effort);
+  if (shadowed && !(await ctx.ui.confirm("Higher-priority settings", "Project or per-model settings override this preference at startup. Save and use your selection in this session anyway?"))) return;
+  if (!(await ctx.ui.confirm("Save and use Pi default?", `${provider}/${modelId}, effort ${choice}\nScope: ${scope}\n${settingsPath(ctx.cwd, scope)}`))) return;
+  // Parse before changing session state. A malformed file must never be overwritten.
+  readSettings(settingsPath(ctx.cwd, scope));
+  const previousModel = ctx.model;
+  const previousEffort = pi.getThinkingLevel();
+  if (!(await pi.setModel(model))) {
+    ctx.ui.notify("Could not switch model. Defaults were not changed.", "warning");
+    return;
+  }
+  const requested = effort ?? effective.effort ?? "medium";
+  try {
+    pi.setThinkingLevel(requested);
+    const applied = pi.getThinkingLevel();
+    if (effort !== undefined && applied !== effort && !(await ctx.ui.confirm("Pi adjusted the effort", `Requested ${effort}; Pi uses ${applied}. Save ${applied} instead?`))) {
+      if (previousModel) await pi.setModel(previousModel);
+      pi.setThinkingLevel(previousEffort);
+      return;
+    }
+    patchSettings(settingsPath(ctx.cwd, scope), data => setPiDefault(data, provider, modelId, effort === undefined ? undefined : applied));
+    ctx.ui.notify(`Using ${provider}/${modelId}, effort ${applied}. Saved ${scope} Pi default.${shadowed ? " Higher-priority startup settings still apply." : ""}`, "info");
+  } catch (error) {
+    if (previousModel) await pi.setModel(previousModel);
+    pi.setThinkingLevel(previousEffort);
+    throw error;
+  }
+}
+
+function display(value: unknown): string {
+  if (value === undefined) return "agent-defined / fallback";
+  if (value === false) return "off";
+  return String(value);
+}
+async function assignModel(ctx: any, config: ModelsConfig, title: string): Promise<{ provider: string; modelId: string } | undefined> {
+  const rows = rankModelsForDefaults(config, ctx);
+  if (!rows.length) { ctx.ui.notify("No models available to assign.", "warning"); return; }
+  const action = await pickerDialog(ctx, rows, title, true);
+  return action?.kind === "load" ? action : undefined;
+}
+export async function defaultsFlow(pi: any, ctx: any, config: ModelsConfig): Promise<void> {
+  let scope: Scope = "user";
+  for (;;) {
+    const discovery = await discoverRoles(ctx.cwd, pi, ctx.model?.provider, trusted(pi, ctx));
+    const user = readSettings(settingsPath(ctx.cwd, "user"));
+    const project = projectSettings(pi, ctx, ctx.cwd);
+    const agentUser = readSettings(settingsPath(discovery.projectRoot, "user"));
+    const agentProject = projectSettings(pi, ctx, discovery.projectRoot);
+    const main = piPreference(user, project);
+    const roles = discovery.roles;
+    const modelFallback = roleField(agentUser, agentProject, ctx.model?.provider, undefined, "model");
+    const thinkingFallback = roleField(agentUser, agentProject, ctx.model?.provider, undefined, "thinking");
+    const options = [
+      `Scope: ${scope} (select to change)`,
+      `Pi session: ${main.provider ?? "auto"}/${main.model ?? "auto"} | ${main.effort ?? "automatic"} [${main.source}]`,
+      `Subagent fallback: ${display(modelFallback.value)} | ${display(thinkingFallback.value)}`,
+      ...roles.map(role => {
+        const model = roleField(agentUser, agentProject, ctx.model?.provider, role.name, "model");
+        const effort = roleField(agentUser, agentProject, ctx.model?.provider, role.name, "thinking");
+        return `${role.name}: ${display(model.value ?? role.model)} | ${display(effort.value ?? role.thinking)} [${model.source}; ${effort.source}]${role.runner ? " [external runner]" : ""}`;
+      }),
+      ...(discovery.warning ? ["Agent discovery details"] : []),
+      "Done",
+    ];
+    const selected = await ctx.ui.select(`BMS defaults\nSaved settings, not running-child state. Agent changes require /reload.\n${scope === "user" ? settingsPath(ctx.cwd, scope) : "Pi: " + settingsPath(ctx.cwd, scope) + "\nAgents: " + settingsPath(discovery.projectRoot, scope)}`, options);
+    if (!selected || selected === "Done") return;
+    const index = options.indexOf(selected);
+    if (index === 0) {
+      if (!trusted(pi, ctx)) { ctx.ui.notify("Project defaults require a trusted project.", "warning"); continue; }
+      scope = scope === "user" ? "project" : "user";
+    } else if (index === 1) {
+      const model = await assignModel(ctx, config, "Choose Pi default model");
+      if (model) await setMainDefault(pi, ctx, model.provider, model.modelId, scope);
+    } else if (selected === "Agent discovery details") {
+      ctx.ui.notify(discovery.warning!, "warning");
+    } else {
+      const role = index === 2 ? undefined : roles[index - 3];
+      await editRole(pi, ctx, config, scope, discovery.projectRoot, role, agentUser, agentProject);
+    }
+  }
+}
+async function editRole(pi: any, ctx: any, config: ModelsConfig, scope: Scope, root: string, role: AgentRole | undefined, user: JsonObject, project: JsonObject): Promise<void> {
+  const title = role?.name ?? "Subagent fallback";
+  const path = settingsPath(root, scope);
+  if (role?.runner) {
+    ctx.ui.notify("External runner defaults are not editable with the Pi registry picker. Use the runner's own configuration.", "warning");
+    return;
+  }
+  const action = await ctx.ui.select(`${title}\nScope: ${scope}. Provider-specific and project overrides may take precedence.\n${path}`, ["Choose model", "Inherit parent model", "Remove model override", "Choose effort", "Remove effort override", "Back"]);
+  if (!action || action === "Back") return;
+  let field: "model" | "thinking" = "model";
+  let value: string | false | undefined;
+  if (action === "Choose model") {
+    const selected = await assignModel(ctx, config, `Choose model for ${title}`);
+    if (!selected) return;
+    value = `${selected.provider}/${selected.modelId}`;
+  } else if (action === "Inherit parent model") value = "inherit";
+  else if (action === "Choose effort") {
+    field = "thinking";
+    const selected = roleField(user, project, ctx.model?.provider, role?.name, "model").value ?? role?.model;
+    const ref = typeof selected === "string" && selected !== "inherit" ? selected.replace(/:(off|minimal|low|medium|high|xhigh|max)$/, "") : `${ctx.model?.provider}/${ctx.model?.id}`;
+    const split = ref.indexOf("/");
+    const model = split > 0 ? ctx.modelRegistry.find(ref.slice(0, split), ref.slice(split + 1)) : undefined;
+    const effort = await chooseEffort(ctx, ref, model);
+    if (effort === undefined) return;
+    value = effort === "automatic" ? undefined : effort;
+  } else if (action === "Remove effort override") field = "thinking";
+  if (!(await ctx.ui.confirm(`Save ${title}?`, `${field}: ${value ?? "remove override"}\n${path}\nReload Pi before relying on the new child defaults. Removing effort restores agent-defined/fallback behavior; it does not force parent inheritance.`))) return;
+  patchSettings(path, data => setRoleField(data, role?.name, field, value));
+  ctx.ui.notify(`Saved ${title} ${field}. Run /reload to refresh subagent defaults.`, "info");
+}

package/extensions/lib/effort-editor.ts

@@ -0,0 +1,69 @@
+import type { FlowCtx } from "./flows.ts";
+import { capabilities, EFFORTS, isEffort, metadataPath, normalizeEfforts, patchSettings, readSettings, saveCapability, settingsPath, type Capability, type Effort } from "./defaults-store.ts";
+
+export interface EffortDraft { capability: Capability; preferred?: Effort }
+export async function editModelEfforts(ctx: FlowCtx, key: string, reasoning: boolean, reported?: Effort[]): Promise<EffortDraft | undefined> {
+  const existing = capabilities(key, { reasoning });
+  let levels = !reasoning ? ["off" as const] : reported ?? existing.levels;
+  let source: Capability["source"] = reported ? "provider" : existing.source === "Manual override" ? "manual" : "pi";
+  if (reasoning) {
+    const mode = await ctx.ui.select(`Available efforts for ${key}\n${reported ? "Provider metadata" : existing.source}`, ["Use listed levels", "Configure manually"]);
+    if (!mode) return;
+    if (mode === "Configure manually") {
+      const raw = await ctx.ui.input(`Comma-separated Pi efforts: ${EFFORTS.join(", ")}`, levels.join(", "));
+      if (raw === undefined) return;
+      const parsed = normalizeEfforts(raw.split(",").map(value => value.trim()));
+      if (!parsed) { ctx.ui.notify("Choose one or more valid Pi effort levels. Nothing changed.", "warning"); return; }
+      levels = parsed;
+      source = "manual";
+    }
+  }
+  const previous = readSettings(settingsPath(ctx.cwd ?? process.cwd(), "user")).modelThinkingLevels?.[key];
+  const options = ["automatic", ...levels];
+  if (isEffort(previous) && levels.includes(previous)) options.splice(options.indexOf(previous), 1), options.unshift(previous);
+  const preferred = await ctx.ui.select(`Preferred effort when Pi loads ${key}\nCurrent: ${previous ?? "automatic"}. Saved in user modelThinkingLevels, independently of agent role defaults.`, options);
+  if (preferred === undefined) return;
+  return { capability: { levels, source }, preferred: isEffort(preferred) ? preferred : undefined };
+}
+/** Do not silently invalidate saved defaults when editing model capability hints. */
+export function effortConflicts(data: Record<string, any>, key: string, levels: readonly Effort[], preferred?: Effort): string[] {
+  const conflicts: string[] = [];
+  const check = (label: string, effort: unknown) => {
+    if (isEffort(effort) && !levels.includes(effort)) conflicts.push(`${label}: ${effort}`);
+  };
+  check("Per-model preference", preferred);
+  if (`${data.defaultProvider}/${data.defaultModel}` === key) check("Pi default", preferred ?? data.defaultThinkingLevel);
+  const sub = data.subagents;
+  if (sub?.defaultModel === key) check("Subagent fallback", sub.defaultThinking);
+  const scan = (entries: Record<string, any> | undefined, prefix: string) => {
+    for (const [name, entry] of Object.entries(entries ?? {})) {
+      if (entry.model === key) check(`${prefix}${name}`, entry.thinking);
+    }
+  };
+  scan(sub?.agentOverrides, "Agent ");
+  for (const [provider, entries] of Object.entries(sub?.agentOverridesByProvider ?? {})) scan(entries as any, `${provider} agent `);
+  return conflicts;
+}
+export function saveModelEfforts(ctx: FlowCtx & { cwd?: string }, key: string, draft: EffortDraft): boolean {
+  const userPath = settingsPath(ctx.cwd ?? process.cwd(), "user");
+  const projectPath = settingsPath(ctx.cwd ?? process.cwd(), "project");
+  const project = ctx.isProjectTrusted?.() ? readSettings(projectPath) : {};
+  const conflicts = [
+    ...effortConflicts(readSettings(userPath), key, draft.capability.levels, draft.preferred),
+    ...effortConflicts(project, key, draft.capability.levels, project.modelThinkingLevels?.[key] ?? draft.preferred).map(value => `Project ${value}`),
+  ];
+  if (conflicts.length) {
+    ctx.ui.notify(`Effort update blocked. Change these defaults in /bms-defaults first: ${conflicts.join("; ")}`, "warning");
+    return false;
+  }
+  // Validate the capability file before writing a preference in a different file.
+  readSettings(metadataPath());
+  patchSettings(userPath, data => {
+    const levels = data.modelThinkingLevels ??= {};
+    if (!levels || typeof levels !== "object" || Array.isArray(levels)) throw new Error("Invalid modelThinkingLevels settings");
+    if (draft.preferred === undefined) delete levels[key];
+    else levels[key] = draft.preferred;
+  });
+  saveCapability(key, draft.capability);
+  return true;
+}