@lunchbox-labs/opencode-model-profiles 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lunchbox Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,91 @@
-# Temporary Holding Version
+# OpenCode Model Profiles
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Choose agent models by name: give each agent a `modelRef`, map refs to models in one `models.jsonc`, and switch between profiles of concrete models per worktree with `/model-config`.
+
+Requires Node **22.18+**. Built for OpenCode **1.19.x**, starting at **1.19.0**.
+
+## Install
+
+Add the package to `plugin` in both `opencode.jsonc` (the server plugin resolves models) and `tui.jsonc` (the `/model-config` dialog and fallback toasts):
+
+```jsonc
+{ "plugin": ["@lunchbox-labs/opencode-model-profiles"] }
+```
+
+## Name the model an agent uses
+
+Set `modelRef` in an agent's Markdown frontmatter:
+
+```markdown
+---
+description: Plans and implements changes
+mode: primary
+modelRef: reasoning
+---
+```
+
+or on an agent entry in `opencode.jsonc`:
+
+```jsonc
+{ "agent": { "reviewer": { "modelRef": "reasoning" } } }
+```
+
+A resolved ref sets the agent's `model`, replacing any model the agent sets itself, and its `variant` when the ref names one; otherwise the agent's own `variant` stays. `modelRef` is removed before OpenCode builds the agent, so it never reaches a provider as an option.
+
+## models.jsonc
+
+The plugin reads `models.jsonc` from OpenCode's global config directory (`OPENCODE_CONFIG_DIR`, else `$XDG_CONFIG_HOME/opencode`, else `~/.config/opencode`) each time OpenCode loads a project. To use another file, pass `configFile`, resolved against that directory:
+
+```jsonc
+{
+  "plugin": [
+    [
+      "@lunchbox-labs/opencode-model-profiles",
+      { "configFile": "models/work.jsonc" },
+    ],
+  ],
+}
+```
+
+```jsonc
+{
+  "$schema": "https://cdn.jsdelivr.net/npm/@lunchbox-labs/opencode-model-profiles/schema.json",
+  "defaults": {
+    "reasoning": { "model": "openai/gpt-6-astra", "variant": "high" },
+    "coding": "openai/gpt-5.6-sol",
+    "system": "openai/gpt-5.6-terra",
+  },
+  "profiles": {
+    "anthropic-latest": {
+      "reasoning": { "model": "anthropic/claude-opus-5-5", "variant": "high" },
+      "coding": "anthropic/claude-sonnet-5-5",
+    },
+  },
+  "builtins": { "general": "coding", "title": "system" },
+}
+```
+
+- `defaults` maps ref names to models. A model is `"provider/model"` or `{ "model": "provider/model", "variant": "high" }`.
+- `profiles` maps profile names to refs. A ref the selected profile leaves out comes from `defaults`.
+- `builtins` gives refs to OpenCode's built-in agents: `build`, `plan`, `general`, `explore`, `compaction`, `title` and `summary`. An agent entry that sets its own `modelRef` or `model` wins. Built-ins without a ref keep OpenCode's default model choice.
+- `defaultProfile` (optional) names the profile used when none is saved for the worktree.
+
+A fuller example is in [docs/examples/models.jsonc](docs/examples/models.jsonc).
+
+## Pick a profile
+
+Run `/model-config` (**Model config** in the command palette). It lists **Defaults only** and each profile, with the current one marked along with where it came from, then every ref with the model it resolves to and the agents that use it, then any fallbacks.
+
+Picking a profile saves it for the current worktree in OpenCode's state directory and reloads the project so it applies at once. If a session is busy, the choice is saved, marked **saved, applies on reload**, and applies the next time OpenCode reloads the project; pick it again once the session is idle to apply it now. When `defaultProfile` is set and a choice is saved, **Follow defaultProfile** forgets the saved choice.
+
+`OPENCODE_MODEL_PROFILE=<profile>` selects a profile for one OpenCode process and overrides the saved choice. `/model-config` shows when it is set; a pick made then is saved for later processes.
+
+Precedence: `OPENCODE_MODEL_PROFILE`, then the saved worktree choice, then `defaultProfile`, then defaults only. A profile that `models.jsonc` does not define is skipped in favour of the next.
+
+## Fallbacks
+
+Problems in the configuration never stop OpenCode. A missing or unparsable `models.jsonc`, an invalid entry or a ref that resolves nowhere leaves the affected agents as OpenCode would configure them; invalid entries are skipped one by one, so the rest of the file still applies. An undefined profile is skipped as described above.
+
+A ref whose model no connected provider offers falls back too, to the model OpenCode would use without the ref: the agent's own `model`, a subagent's parent model, else OpenCode's default. The plugin applies refs before OpenCode loads providers, so it saves which models were available in OpenCode's state directory and leaves unavailable refs out from the next start. Until it has checked once, prompts to such a model are moved to the fallback, and once no session is busy and no terminal is open the plugin reloads the project, which restarts its MCP and LSP servers. That covers built-in agents such as `compaction` and `title` that never receive a prompt of their own; in the first process that meets a broken ref they, and commands that name the agent, can still fail until that reload. A prompt that reuses a ref's unavailable model after the ref is fixed falls back too, while a model you set on an agent yourself is left as OpenCode would use it. If a provider connects after the last check, its refs apply again after the first reload.
+
+The TUI shows a warning toast with the first new problem and how many more there are. A problem is toasted once per OpenCode launch, and again after it changes; `/model-config` lists all current ones.

package/dist/apply.d.ts

@@ -0,0 +1,18 @@
+import type { ModelProfilesReport } from "./report.ts";
+import { type RefAssignment } from "./resolution.ts";
+export declare function modelsFilePath(options: unknown, environment?: NodeJS.ProcessEnv): string;
+export interface ResolveInput {
+    configFile: string;
+    worktree: string;
+    environment?: NodeJS.ProcessEnv;
+    /** Models connected providers offered when last checked; refs to others are not applied. Unknown until checked. */
+    availableModels?: ReadonlySet<string>;
+}
+export interface ResolvedModelProfiles {
+    report: ModelProfilesReport;
+    assignments: RefAssignment[];
+}
+/** Replaces `config.agent` with resolved copies and returns what was applied; never throws for bad input files. */
+export declare function resolveModelProfiles(config: Record<string, unknown>, input: ResolveInput): Promise<ResolvedModelProfiles>;
+/** The last resort when resolution fails unexpectedly: OpenCode's models stay, and modelRef never reaches a provider. */
+export declare function stripModelRefs(config: Record<string, unknown>): void;

package/dist/apply.js

@@ -0,0 +1,71 @@
+import path from "node:path";
+import { isRecord, loadModelsDocument, } from "./models-file.js";
+import { applyModelRefs, selectProfile, } from "./resolution.js";
+import { configurationDirectory, processProfile, readSavedSelection, selectionFilePath, stateDirectory, } from "./selection.js";
+export function modelsFilePath(options, environment = process.env) {
+    const directory = configurationDirectory(environment);
+    const configured = isRecord(options) ? options.configFile : undefined;
+    return typeof configured === "string" && configured.trim() !== ""
+        ? path.resolve(directory, configured)
+        : path.join(directory, "models.jsonc");
+}
+function usesModelRefs(agents) {
+    return (isRecord(agents) &&
+        Object.values(agents).some((agent) => isRecord(agent) &&
+            (Object.hasOwn(agent, "modelRef") ||
+                (isRecord(agent.options) &&
+                    Object.hasOwn(agent.options, "modelRef")))));
+}
+/** Replaces `config.agent` with resolved copies and returns what was applied; never throws for bad input files. */
+export async function resolveModelProfiles(config, input) {
+    const environment = input.environment ?? process.env;
+    const selectionFile = selectionFilePath(stateDirectory(environment), input.worktree);
+    const loaded = await loadModelsDocument(input.configFile);
+    const notices = [...loaded.notices];
+    if (loaded.status === "missing" && usesModelRefs(config.agent)) {
+        notices.push(`No models file at ${input.configFile}; agents with a modelRef keep OpenCode's model.`);
+    }
+    const environmentProfile = processProfile(environment);
+    const saved = await readSavedSelection(selectionFile);
+    if (saved.notice !== undefined) {
+        notices.push(saved.notice);
+    }
+    const selection = selectProfile(loaded.document, environmentProfile, saved.profile);
+    const applied = applyModelRefs(config.agent, loaded.document, selection.profile, input.availableModels);
+    if (loaded.status === "loaded") {
+        notices.push(...selection.notices, ...applied.notices);
+    }
+    if (isRecord(config.agent) || Object.keys(applied.agents).length > 0) {
+        config.agent = applied.agents;
+    }
+    const report = {
+        version: 1,
+        configFile: input.configFile,
+        selectionFile,
+        worktree: input.worktree,
+        profiles: Object.keys(loaded.document.profiles),
+        profile: selection.profile,
+        profileSource: selection.source,
+        ...(environmentProfile === undefined ? {} : { environmentProfile }),
+        refs: applied.refs,
+        notices,
+    };
+    return { report, assignments: applied.assignments };
+}
+/** The last resort when resolution fails unexpectedly: OpenCode's models stay, and modelRef never reaches a provider. */
+export function stripModelRefs(config) {
+    if (!isRecord(config.agent)) {
+        return;
+    }
+    config.agent = Object.fromEntries(Object.entries(config.agent).map(([name, agent]) => {
+        if (!isRecord(agent)) {
+            return [name, agent];
+        }
+        const { modelRef: _modelRef, ...rest } = agent;
+        if (isRecord(rest.options)) {
+            const { modelRef: _optionsModelRef, ...options } = rest.options;
+            rest.options = options;
+        }
+        return [name, rest];
+    }));
+}

package/dist/fallback.d.ts

@@ -0,0 +1,49 @@
+import type { RefAssignment } from "./resolution.ts";
+export declare function knownRefModels(directory: string): ReadonlySet<string>;
+export declare function availabilityFilePath(state: string, directory: string): string;
+/** The models last seen for this directory, from memory or the state file; undefined when never checked. */
+export declare function knownAvailableModels(state: string, directory: string): Promise<ReadonlySet<string> | undefined>;
+export declare function availabilityKey(models: ReadonlySet<string>): string;
+/** Remembers the models for this directory and the ref models seen, saving them when they changed; best-effort. */
+export declare function rememberAvailableModels(state: string, directory: string, models: ReadonlySet<string>, assigned?: Iterable<string>): Promise<void>;
+export interface ConnectedProviders {
+    providers: {
+        id: string;
+        models: Record<string, unknown>;
+    }[];
+    default: Record<string, string>;
+}
+/** Reads OpenCode's provider list response; anything unexpected yields undefined so nothing changes. */
+export declare function readConnectedProviders(data: unknown): ConnectedProviders | undefined;
+export declare function availableModels(connected: ConnectedProviders): ReadonlySet<string>;
+/** True when the agents the config hook built no longer match what is available, so a reload would change them. */
+export declare function assignmentsAreStale(assignments: readonly RefAssignment[], available: ReadonlySet<string>): boolean;
+/** OpenCode's recently used models, which it tries before a provider's default when no `model` is set. */
+export declare function recentModels(state: string): Promise<string[]>;
+export interface FallbackInput {
+    /** The agent's own model and variant, when it had one besides its ref. */
+    own?: {
+        model: string;
+        variant?: string;
+    };
+    /** The model of the session that started this subagent, which OpenCode gives a subagent without a model. */
+    parentModel?: string;
+    available: ReadonlySet<string>;
+    connected: ConnectedProviders;
+    /** The top-level `model` from OpenCode's config. */
+    configuredModel?: string;
+    /** Provider ids configured under `provider`, which OpenCode prefers for its default. */
+    configuredProviders: readonly string[];
+    recent: readonly string[];
+}
+export interface FallbackModel {
+    providerID: string;
+    modelID: string;
+    variant?: string;
+}
+/**
+ * The model OpenCode would use for the agent without its ref: the agent's own `model`, else for a subagent its
+ * parent's model, else OpenCode's default (the configured `model`, a recently used model, then a connected
+ * provider's default), skipping unavailable ones.
+ */
+export declare function fallbackModel(input: FallbackInput): FallbackModel | undefined;

package/dist/fallback.js

@@ -0,0 +1,169 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { isRecord } from "./models-file.js";
+/**
+ * Models connected providers offered when last checked, per instance directory. OpenCode keeps the plugin module
+ * loaded when it reloads a project, so this outlives the reload that lets the config hook leave unavailable refs
+ * unapplied. It is also saved in OpenCode's state directory, so a new process (such as `opencode run`) leaves them
+ * out from the start.
+ */
+const availability = new Map();
+/**
+ * Every model a ref has put on an agent, per directory, also saved. A session can keep asking for one after its ref
+ * is fixed or left out, and only those are moved when OpenCode took the model from the agent or the session, so a
+ * model the user set by hand still fails as OpenCode would.
+ */
+const refModels = new Map();
+export function knownRefModels(directory) {
+    return refModels.get(directory) ?? new Set();
+}
+export function availabilityFilePath(state, directory) {
+    const key = createHash("sha256")
+        .update(process.platform === "win32"
+        ? path.resolve(directory).toLowerCase()
+        : path.resolve(directory))
+        .digest("hex")
+        .slice(0, 32);
+    return path.join(state, "model-profiles", "available", `${key}.json`);
+}
+/** The models last seen for this directory, from memory or the state file; undefined when never checked. */
+export async function knownAvailableModels(state, directory) {
+    const known = availability.get(directory);
+    if (known !== undefined) {
+        return known;
+    }
+    try {
+        const value = JSON.parse(await readFile(availabilityFilePath(state, directory), "utf8"));
+        if (isRecord(value) &&
+            value.version === 1 &&
+            Array.isArray(value.models) &&
+            value.models.every((model) => typeof model === "string")) {
+            const models = new Set(value.models);
+            availability.set(directory, models);
+            if (!refModels.has(directory) &&
+                Array.isArray(value.refModels) &&
+                value.refModels.every((model) => typeof model === "string")) {
+                refModels.set(directory, new Set(value.refModels));
+            }
+            return models;
+        }
+    }
+    catch {
+        // A missing or unreadable file means availability is not known yet.
+    }
+    return undefined;
+}
+export function availabilityKey(models) {
+    return [...models].sort().join("\n");
+}
+/** Remembers the models for this directory and the ref models seen, saving them when they changed; best-effort. */
+export async function rememberAvailableModels(state, directory, models, assigned = []) {
+    const previous = availability.get(directory);
+    const previousRefs = knownRefModels(directory);
+    const refs = new Set([...previousRefs, ...assigned]);
+    availability.set(directory, models);
+    refModels.set(directory, refs);
+    if (previous !== undefined &&
+        availabilityKey(previous) === availabilityKey(models) &&
+        refs.size === previousRefs.size) {
+        return;
+    }
+    const file = availabilityFilePath(state, directory);
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        await mkdir(path.dirname(file), { recursive: true });
+        await writeFile(temporary, `${JSON.stringify({ version: 1, directory, models: [...models].sort(), refModels: [...refs].sort() })}\n`, "utf8");
+        await rename(temporary, file);
+    }
+    catch {
+        // Without the file the next process learns availability on its first prompt instead.
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+/** Reads OpenCode's provider list response; anything unexpected yields undefined so nothing changes. */
+export function readConnectedProviders(data) {
+    if (!isRecord(data) || !Array.isArray(data.providers)) {
+        return undefined;
+    }
+    const providers = data.providers.flatMap((provider) => isRecord(provider) &&
+        typeof provider.id === "string" &&
+        isRecord(provider.models)
+        ? [{ id: provider.id, models: provider.models }]
+        : []);
+    const defaults = isRecord(data.default)
+        ? Object.fromEntries(Object.entries(data.default).filter((entry) => typeof entry[1] === "string"))
+        : {};
+    return { providers, default: defaults };
+}
+export function availableModels(connected) {
+    return new Set(connected.providers.flatMap((provider) => Object.keys(provider.models).map((model) => `${provider.id}/${model}`)));
+}
+/** True when the agents the config hook built no longer match what is available, so a reload would change them. */
+export function assignmentsAreStale(assignments, available) {
+    return assignments.some((assignment) => assignment.applied !== available.has(assignment.model));
+}
+/** OpenCode's recently used models, which it tries before a provider's default when no `model` is set. */
+export async function recentModels(state) {
+    try {
+        const value = JSON.parse(await readFile(path.join(state, "model.json"), "utf8"));
+        if (!isRecord(value) || !Array.isArray(value.recent)) {
+            return [];
+        }
+        return value.recent.flatMap((entry) => isRecord(entry) &&
+            typeof entry.providerID === "string" &&
+            typeof entry.modelID === "string"
+            ? [`${entry.providerID}/${entry.modelID}`]
+            : []);
+    }
+    catch {
+        return [];
+    }
+}
+function split(model) {
+    const separator = model.indexOf("/");
+    return {
+        providerID: model.slice(0, separator),
+        modelID: model.slice(separator + 1),
+    };
+}
+function hasVariant(connected, model, variant) {
+    const { providerID, modelID } = split(model);
+    const info = connected.providers.find((provider) => provider.id === providerID)?.models[modelID];
+    // Only a model that lists its variants can be known not to offer one.
+    return (!isRecord(info) ||
+        !isRecord(info.variants) ||
+        Object.hasOwn(info.variants, variant));
+}
+/**
+ * The model OpenCode would use for the agent without its ref: the agent's own `model`, else for a subagent its
+ * parent's model, else OpenCode's default (the configured `model`, a recently used model, then a connected
+ * provider's default), skipping unavailable ones.
+ */
+export function fallbackModel(input) {
+    const { own, available, connected } = input;
+    if (own !== undefined && available.has(own.model)) {
+        return {
+            ...split(own.model),
+            ...(own.variant !== undefined &&
+                hasVariant(connected, own.model, own.variant)
+                ? { variant: own.variant }
+                : {}),
+        };
+    }
+    const provider = connected.providers.find((candidate) => input.configuredProviders.length === 0 ||
+        input.configuredProviders.includes(candidate.id));
+    const providerDefault = provider === undefined ? undefined : connected.default[provider.id];
+    const candidates = [
+        input.parentModel,
+        input.configuredModel,
+        ...input.recent,
+        provider === undefined || providerDefault === undefined
+            ? undefined
+            : `${provider.id}/${providerDefault}`,
+    ];
+    const model = candidates.find((candidate) => candidate !== undefined && available.has(candidate));
+    return model === undefined ? undefined : split(model);
+}

package/dist/model-config-view.d.ts

@@ -0,0 +1,36 @@
+import type { TuiDialogSelectOption } from "@opencode-ai/plugin/tui";
+import type { ModelProfilesReport } from "./report.ts";
+import { type SavedProfile } from "./selection.ts";
+export declare function profileLabel(profile: string | null): string;
+type RefResolution = ModelProfilesReport["refs"][number];
+export interface ConnectedProvider {
+    id: string;
+    models: Record<string, unknown>;
+}
+/**
+ * The server's config hook runs before providers load, so the TUI checks resolved models against them until
+ * the server has marked a ref unavailable itself. With no provider list (not loaded yet) nothing is reported.
+ */
+export declare function unavailableModelNotices(refs: readonly RefResolution[], providers: readonly ConnectedProvider[]): string[];
+export interface ModelConfigViewInput {
+    report: ModelProfilesReport;
+    /** Profiles in models.jsonc now, which may be newer than the report. */
+    profiles: string[];
+    /** The worktree's saved choice now; it differs from the report while a pick waits for a reload. */
+    savedProfile: SavedProfile;
+    defaultProfile: string | undefined;
+    notices: string[];
+}
+export type ModelConfigChoice = {
+    kind: "save";
+    profile: string | null;
+} | {
+    kind: "followDefaultProfile";
+};
+export declare function modelConfigOptions(input: ModelConfigViewInput): TuiDialogSelectOption<string>[];
+/** Fallback rows can be cut off in the list, so choosing one shows its full text. */
+export declare function selectedNotice(value: string, notices: readonly string[]): string | undefined;
+export declare function selectedChoice(value: string): ModelConfigChoice | undefined;
+/** One toast line per problem would bury the message, so a toast names the first and points to the dialog. */
+export declare function fallbackToastLines(notices: readonly string[]): string[];
+export {};

package/dist/model-config-view.js

@@ -0,0 +1,131 @@
+import { unavailableModelNotice } from "./resolution.js";
+import { processProfileVariable } from "./selection.js";
+export function profileLabel(profile) {
+    return profile ?? "Defaults only";
+}
+function modelLabel(ref) {
+    if (ref.model === undefined) {
+        return "not defined, OpenCode's model";
+    }
+    const model = ref.variant === undefined ? ref.model : `${ref.model} (${ref.variant})`;
+    return ref.unavailable === true
+        ? `${model}, unavailable, OpenCode's model`
+        : model;
+}
+/**
+ * The server's config hook runs before providers load, so the TUI checks resolved models against them until
+ * the server has marked a ref unavailable itself. With no provider list (not loaded yet) nothing is reported.
+ */
+export function unavailableModelNotices(refs, providers) {
+    if (providers.length === 0) {
+        return [];
+    }
+    return refs.flatMap((ref) => {
+        if (ref.model === undefined ||
+            ref.unavailable === true ||
+            ref.agents.length === 0) {
+            return [];
+        }
+        const separator = ref.model.indexOf("/");
+        const providerId = ref.model.slice(0, separator);
+        const modelId = ref.model.slice(separator + 1);
+        const provider = providers.find((candidate) => candidate.id === providerId);
+        if (provider !== undefined && Object.hasOwn(provider.models, modelId)) {
+            return [];
+        }
+        return [
+            unavailableModelNotice(ref.ref, ref.model, ref.agents, provider !== undefined),
+        ];
+    });
+}
+const sourceLabels = {
+    environment: processProfileVariable,
+    saved: "saved",
+    defaultProfile: "defaultProfile",
+    none: "no profile chosen",
+};
+const followDefaultProfileValue = "follow-default-profile";
+export function modelConfigOptions(input) {
+    const { report, savedProfile, defaultProfile } = input;
+    const profileCategory = report.environmentProfile === undefined
+        ? "Profile for this worktree"
+        : `Profile for this worktree (${processProfileVariable}=${report.environmentProfile} overrides it)`;
+    const pending = savedProfile !== undefined &&
+        (report.profileSource !== "saved" || savedProfile !== report.profile);
+    const footer = (profile) => {
+        const marks = [
+            ...(profile === report.profile
+                ? [`current, ${sourceLabels[report.profileSource]}`]
+                : []),
+            ...(pending && profile === savedProfile
+                ? [
+                    report.environmentProfile === undefined
+                        ? "saved, applies on reload"
+                        : "saved for later processes",
+                ]
+                : []),
+        ];
+        return marks.length === 0 ? {} : { footer: marks.join("; ") };
+    };
+    const choices = [null, ...input.profiles];
+    return [
+        ...(defaultProfile === undefined || savedProfile === undefined
+            ? []
+            : [
+                {
+                    title: `Follow defaultProfile (${defaultProfile})`,
+                    value: followDefaultProfileValue,
+                    category: profileCategory,
+                    description: "Forget the saved choice for this worktree",
+                },
+            ]),
+        ...choices.map((profile) => ({
+            title: profileLabel(profile),
+            value: profile === null ? "defaults" : `profile:${profile}`,
+            category: profileCategory,
+            ...footer(profile),
+            description: profile === null ? "Use only the defaults in models.jsonc" : undefined,
+        })),
+        ...report.refs.map((ref) => ({
+            title: `${ref.ref} → ${modelLabel(ref)}`,
+            value: `ref:${ref.ref}`,
+            category: "Model refs",
+            description: ref.agents.length === 0 ? "No agents" : ref.agents.join(", "),
+            footer: ref.source === "unresolved" || ref.unavailable === true
+                ? "fallback"
+                : ref.source,
+        })),
+        ...input.notices.map((notice, index) => ({
+            title: notice,
+            value: `notice:${index}`,
+            category: "Fallbacks",
+        })),
+    ];
+}
+/** Fallback rows can be cut off in the list, so choosing one shows its full text. */
+export function selectedNotice(value, notices) {
+    return value.startsWith("notice:")
+        ? notices[Number(value.slice("notice:".length))]
+        : undefined;
+}
+export function selectedChoice(value) {
+    if (value === followDefaultProfileValue) {
+        return { kind: "followDefaultProfile" };
+    }
+    if (value === "defaults") {
+        return { kind: "save", profile: null };
+    }
+    return value.startsWith("profile:")
+        ? { kind: "save", profile: value.slice("profile:".length) }
+        : undefined;
+}
+/** One toast line per problem would bury the message, so a toast names the first and points to the dialog. */
+export function fallbackToastLines(notices) {
+    const more = notices.length - 1;
+    return more <= 0
+        ? [...notices]
+        : [
+            ...notices.slice(0, 1),
+            `${more} more ${more === 1 ? "problem" : "problems"}; see /model-config.`,
+        ];
+}

package/dist/models-file.d.ts

@@ -0,0 +1,22 @@
+export declare const builtInAgentNames: readonly ["build", "plan", "general", "explore", "compaction", "title", "summary"];
+export interface ModelChoice {
+    model: string;
+    variant?: string;
+}
+export interface ModelsDocument {
+    defaultProfile?: string;
+    defaults: Record<string, ModelChoice>;
+    profiles: Record<string, Record<string, ModelChoice>>;
+    builtins: Record<string, string>;
+}
+export interface LoadedModels {
+    document: ModelsDocument;
+    /** "unusable" means the file exists but could not be read or parsed, so it contributes nothing. */
+    status: "loaded" | "missing" | "unusable";
+    notices: string[];
+}
+export declare function emptyModelsDocument(): ModelsDocument;
+export declare function ownValue<Value>(record: Record<string, Value>, key: string): Value | undefined;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function parseModelsDocument(text: string, path: string): LoadedModels;
+export declare function loadModelsDocument(path: string): Promise<LoadedModels>;