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

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.
+
+The plugin does not check that a model exists when it applies a ref, so an agent whose ref names a model no connected provider offers fails when used. The TUI warns about such refs.
+
+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,11 @@
+import type { ModelProfilesReport } from "./report.ts";
+export declare function modelsFilePath(options: unknown, environment?: NodeJS.ProcessEnv): string;
+export interface ResolveInput {
+    configFile: string;
+    worktree: string;
+    environment?: NodeJS.ProcessEnv;
+}
+/** 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<ModelProfilesReport>;
+/** 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,70 @@
+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);
+    if (loaded.status === "loaded") {
+        notices.push(...selection.notices, ...applied.notices);
+    }
+    if (isRecord(config.agent) || Object.keys(applied.agents).length > 0) {
+        config.agent = applied.agents;
+    }
+    return {
+        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,
+    };
+}
+/** 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/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 cannot see which providers are connected, so the TUI checks resolved models against them.
+ * With no provider list (not loaded yet) nothing is reported, rather than every ref.
+ */
+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,128 @@
+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";
+    }
+    return ref.variant === undefined
+        ? ref.model
+        : `${ref.model} (${ref.variant})`;
+}
+/**
+ * The server cannot see which providers are connected, so the TUI checks resolved models against them.
+ * With no provider list (not loaded yet) nothing is reported, rather than every ref.
+ */
+export function unavailableModelNotices(refs, providers) {
+    if (providers.length === 0) {
+        return [];
+    }
+    return refs.flatMap((ref) => {
+        if (ref.model === undefined || 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 [];
+        }
+        const reason = provider === undefined
+            ? `provider "${providerId}" is not connected`
+            : `"${providerId}" has no model "${modelId}"`;
+        return [
+            `Ref "${ref.ref}" uses ${ref.model}, but ${reason}; ${ref.agents.join(", ")} will fail until you fix the ref or pick another profile.`,
+        ];
+    });
+}
+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" ? "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>;

package/dist/models-file.js

@@ -0,0 +1,155 @@
+import { readFile } from "node:fs/promises";
+import { parse, printParseErrorCode } from "jsonc-parser";
+export const builtInAgentNames = [
+    "build",
+    "plan",
+    "general",
+    "explore",
+    "compaction",
+    "title",
+    "summary",
+];
+export function emptyModelsDocument() {
+    return { defaults: {}, profiles: {}, builtins: {} };
+}
+export function ownValue(record, key) {
+    return Object.hasOwn(record, key) ? record[key] : undefined;
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyName(value) {
+    return typeof value === "string" && value.trim() !== "";
+}
+const modelIdentifierPattern = /^[^\s/]+\/\S+$/;
+function readModelChoice(value) {
+    if (typeof value === "string") {
+        return modelIdentifierPattern.test(value) ? { model: value } : undefined;
+    }
+    if (!isRecord(value) ||
+        typeof value.model !== "string" ||
+        !modelIdentifierPattern.test(value.model)) {
+        return undefined;
+    }
+    if (value.variant === undefined) {
+        return { model: value.model };
+    }
+    return isNonEmptyName(value.variant)
+        ? { model: value.model, variant: value.variant }
+        : undefined;
+}
+function readModelChoices(value, location, notices) {
+    const choices = {};
+    if (value === undefined) {
+        return choices;
+    }
+    if (!isRecord(value)) {
+        notices.push(`${location} is not an object of model refs; ignored.`);
+        return choices;
+    }
+    for (const [ref, entry] of Object.entries(value)) {
+        const choice = readModelChoice(entry);
+        if (choice === undefined || !isNonEmptyName(ref)) {
+            notices.push(`${location}.${ref} is not "provider/model" or { "model", "variant" }; skipped.`);
+            continue;
+        }
+        choices[ref] = choice;
+    }
+    return choices;
+}
+function lineAndColumn(text, offset) {
+    const before = text.slice(0, offset).split("\n");
+    return `line ${before.length}, column ${(before.at(-1)?.length ?? 0) + 1}`;
+}
+export function parseModelsDocument(text, path) {
+    const notices = [];
+    const errors = [];
+    const value = parse(text, errors, {
+        allowTrailingComma: true,
+        disallowComments: false,
+    });
+    const firstError = errors.at(0);
+    if (firstError !== undefined) {
+        notices.push(`${path} has a syntax error (${printParseErrorCode(firstError.error)} at ${lineAndColumn(text, firstError.offset)}); its model refs are ignored.`);
+        return { document: emptyModelsDocument(), status: "unusable", notices };
+    }
+    if (!isRecord(value)) {
+        notices.push(`${path} is not a JSON object; its model refs are ignored.`);
+        return { document: emptyModelsDocument(), status: "unusable", notices };
+    }
+    const knownKeys = [
+        "$schema",
+        "defaultProfile",
+        "defaults",
+        "profiles",
+        "builtins",
+    ];
+    for (const key of Object.keys(value)) {
+        if (!knownKeys.includes(key)) {
+            notices.push(`Unknown top-level key "${key}" in ${path}; ignored.`);
+        }
+    }
+    const document = emptyModelsDocument();
+    document.defaults = readModelChoices(value.defaults, "defaults", notices);
+    if (value.profiles !== undefined && !isRecord(value.profiles)) {
+        notices.push("profiles is not an object of profiles; ignored.");
+    }
+    else {
+        for (const [name, refs] of Object.entries(value.profiles ?? {})) {
+            if (!isNonEmptyName(name)) {
+                notices.push("A profile with an empty name was skipped.");
+                continue;
+            }
+            document.profiles[name] = readModelChoices(refs, `profiles.${name}`, notices);
+        }
+    }
+    if (value.builtins !== undefined && !isRecord(value.builtins)) {
+        notices.push("builtins is not an object of agent names; ignored.");
+    }
+    else {
+        const knownBuiltIns = builtInAgentNames;
+        for (const [agent, ref] of Object.entries(value.builtins ?? {})) {
+            if (!knownBuiltIns.includes(agent)) {
+                notices.push(`builtins.${agent} is not a built-in agent (${builtInAgentNames.join(", ")}); skipped.`);
+            }
+            else if (!isNonEmptyName(ref)) {
+                notices.push(`builtins.${agent} is not a ref name; skipped.`);
+            }
+            else {
+                document.builtins[agent] = ref;
+            }
+        }
+    }
+    if (value.defaultProfile !== undefined) {
+        if (isNonEmptyName(value.defaultProfile)) {
+            document.defaultProfile = value.defaultProfile;
+        }
+        else {
+            notices.push("defaultProfile is not a profile name; ignored.");
+        }
+    }
+    return { document, status: "loaded", notices };
+}
+export async function loadModelsDocument(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+            return {
+                document: emptyModelsDocument(),
+                status: "missing",
+                notices: [],
+            };
+        }
+        return {
+            document: emptyModelsDocument(),
+            status: "unusable",
+            notices: [
+                `Could not read ${path} (${error instanceof Error ? error.message : String(error)}); its model refs are ignored.`,
+            ],
+        };
+    }
+    return parseModelsDocument(text, path);
+}

package/dist/report.d.ts

@@ -0,0 +1,17 @@
+import type { ProfileSource, RefResolution } from "./resolution.ts";
+export declare const packageName = "@lunchbox-labs/opencode-model-profiles";
+/** What the server applied, published in its own plugin entry so the TUI can read it through /config. */
+export interface ModelProfilesReport {
+    version: 1;
+    configFile: string;
+    selectionFile: string;
+    worktree: string;
+    profiles: string[];
+    profile: string | null;
+    profileSource: ProfileSource;
+    environmentProfile?: string;
+    refs: RefResolution[];
+    notices: string[];
+}
+export declare function publishReport(config: Record<string, unknown>, options: unknown, report: ModelProfilesReport): boolean;
+export declare function readReport(config: unknown): ModelProfilesReport | undefined;

package/dist/report.js

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isRecord } from "./models-file.js";
+export const packageName = "@lunchbox-labs/opencode-model-profiles";
+const reportKey = "modelProfilesReport";
+const packageRoot = path.resolve(fileURLToPath(new URL("../", import.meta.url)));
+function isOwnSpecifier(specifier) {
+    if (typeof specifier !== "string") {
+        return false;
+    }
+    if (specifier === packageName || specifier.startsWith(`${packageName}@`)) {
+        return true;
+    }
+    if (!specifier.startsWith("file:")) {
+        return false;
+    }
+    try {
+        const target = path.resolve(fileURLToPath(specifier));
+        return target === packageRoot || target.startsWith(packageRoot + path.sep);
+    }
+    catch {
+        return false;
+    }
+}
+export function publishReport(config, options, report) {
+    if (!Array.isArray(config.plugin)) {
+        return false;
+    }
+    const plugins = [...config.plugin];
+    const index = plugins.findIndex((entry) => Array.isArray(entry)
+        ? entry[1] === options || isOwnSpecifier(entry[0])
+        : isOwnSpecifier(entry));
+    if (index < 0) {
+        return false;
+    }
+    const entry = plugins[index];
+    const specifier = Array.isArray(entry) ? entry[0] : entry;
+    const entryOptions = Array.isArray(entry) ? entry[1] : undefined;
+    plugins[index] = [
+        specifier,
+        {
+            ...(isRecord(entryOptions) ? entryOptions : {}),
+            [reportKey]: JSON.parse(JSON.stringify(report)),
+        },
+    ];
+    config.plugin = plugins;
+    return true;
+}
+function isReport(value) {
+    return (isRecord(value) &&
+        value.version === 1 &&
+        typeof value.configFile === "string" &&
+        typeof value.selectionFile === "string" &&
+        typeof value.worktree === "string" &&
+        (value.profile === null || typeof value.profile === "string") &&
+        Array.isArray(value.profiles) &&
+        Array.isArray(value.refs) &&
+        Array.isArray(value.notices));
+}
+export function readReport(config) {
+    if (!isRecord(config) || !Array.isArray(config.plugin)) {
+        return undefined;
+    }
+    for (const entry of config.plugin) {
+        const report = Array.isArray(entry) && isRecord(entry[1])
+            ? entry[1][reportKey]
+            : undefined;
+        if (isReport(report)) {
+            return report;
+        }
+    }
+    return undefined;
+}

package/dist/resolution.d.ts

@@ -0,0 +1,27 @@
+import { type ModelsDocument } from "./models-file.ts";
+import type { SavedProfile } from "./selection.ts";
+export type ProfileSource = "environment" | "saved" | "defaultProfile" | "none";
+export interface ProfileSelection {
+    profile: string | null;
+    source: ProfileSource;
+    notices: string[];
+}
+/** Takes the first choice that names a defined profile (or "defaults only"); undefined profiles fall through to the next. */
+export declare function selectProfile(document: ModelsDocument, environmentProfile: string | undefined, savedProfile: SavedProfile): ProfileSelection;
+export interface RefResolution {
+    ref: string;
+    model?: string;
+    variant?: string;
+    source: "profile" | "defaults" | "unresolved";
+    agents: string[];
+}
+export interface AppliedModelRefs {
+    agents: Record<string, unknown>;
+    refs: RefResolution[];
+    notices: string[];
+}
+/**
+ * Returns a new agent map and leaves the given one untouched: OpenCode keeps the global config's
+ * agent objects for the whole process, so mutating them would lose each modelRef on the next reload.
+ */
+export declare function applyModelRefs(configuredAgents: unknown, document: ModelsDocument, profile: string | null): AppliedModelRefs;