akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/core/config/convert-engine-references.js

@@ -0,0 +1,114 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Where the engines of improve strategies, index passes and workflow gates went: the
+ * `connection` / `harness` they name now, or the process they moved to. See `convert-engines.ts`.
+ */
+import { isDeepStrictEqual } from "node:util";
+import { isRecord } from "../common.js";
+import { objectAt, str } from "./convert-engines-shared.js";
+/** What a strategy's process, quality gate or judgment once said about where it runs and how. */
+const EXECUTION_KEYS = ["connection", "harness", "model", "llm", "timeoutMs"];
+/** Rewrite the `engine` of `holder` as the `connection` or `harness` it names now, unless the holder already says. */
+export function retargeter(conversion, target) {
+    return (holder, where, harnessOk = true) => {
+        if (!isRecord(holder) || !("engine" in holder))
+            return;
+        conversion.changed = true;
+        const engine = str(holder.engine);
+        delete holder.engine;
+        const found = engine === undefined ? undefined : target(engine);
+        if (found === undefined)
+            conversion.notes.push(`${where}: engine ${JSON.stringify(engine)} is not carried over.`);
+        else if ("harness" in found && !harnessOk)
+            conversion.notes.push(`${where}: index passes run on connections only; engine "${engine}" is not carried over.`);
+        else
+            for (const [key, value] of Object.entries(found))
+                holder[key] ??= value;
+    };
+}
+/**
+ * A strategy's `engine`, `model`, `llm` and `timeoutMs` are dropped (it says which processes run, not where), and
+ * where its processes, quality gates and triage judgment said a process runs moves to `improve.processes.<name>` /
+ * `improve.qualityGate`; the first strategy to say it wins.
+ */
+export function moveStrategyExecution(improve, conversion, retarget) {
+    if (!isRecord(improve.strategies))
+        return;
+    const hoist = (holder, from, place, destination) => {
+        if (!isRecord(holder))
+            return;
+        retarget(holder, `${from}.engine`);
+        const found = EXECUTION_KEYS.filter((key) => key in holder);
+        if (found.length === 0)
+            return;
+        conversion.changed = true;
+        const into = destination();
+        for (const key of found) {
+            const value = holder[key];
+            delete holder[key];
+            const names = key === "connection" || key === "harness";
+            const taken = names ? "connection" in into || "harness" in into : key in into;
+            if (!taken)
+                into[key] = value;
+            else if (!isDeepStrictEqual(into[key], value))
+                conversion.notes.push(`${from}.${key}: ${place} already says where this runs; the first choice is kept.`);
+        }
+    };
+    const processEntry = (name) => () => objectAt(objectAt(improve, "processes"), name);
+    for (const [strategyName, strategy] of Object.entries(improve.strategies)) {
+        if (!isRecord(strategy))
+            continue;
+        for (const key of ["engine", "model", "llm", "timeoutMs"]) {
+            if (key in strategy) {
+                delete strategy[key];
+                conversion.changed = true;
+                conversion.notes.push(`improve.strategies.${strategyName}.${key}: a strategy says which processes run, not where; it is dropped.`);
+            }
+        }
+        for (const [processName, process] of Object.entries(isRecord(strategy.processes) ? strategy.processes : {})) {
+            const where = `improve.strategies.${strategyName}.processes.${processName}`;
+            if (!isRecord(process))
+                continue;
+            // Triage's judgment is the model call; in 0.9 its setting was the nearer one, so it is hoisted first and wins.
+            hoist(process.judgment, `${where}.judgment`, "improve.processes.triage", processEntry("triage"));
+            hoist(process, where, `improve.processes.${processName}`, processEntry(processName));
+            hoist(process.qualityGate, `${where}.qualityGate`, "improve.qualityGate", () => objectAt(improve, "qualityGate"));
+        }
+    }
+}
+/** `defaults.improveStrategy`: `improve.strategy`. */
+export function improveStrategyDefault(out, defaults, improve) {
+    if (defaults.improveStrategy === undefined)
+        return;
+    out.improve = { ...(isRecord(improve) ? improve : {}) };
+    out.improve.strategy ??= defaults.improveStrategy;
+}
+/** `workflow.judgeEngine`: a gate's judge is the default connection or harness now. */
+export function dropJudgeEngine(out, conversion) {
+    const workflow = out.workflow;
+    if (!isRecord(workflow) || !("judgeEngine" in workflow))
+        return;
+    delete workflow.judgeEngine;
+    conversion.changed = true;
+    conversion.notes.push("workflow.judgeEngine: a gate's judge is the default connection or harness now; it is dropped.");
+}
+/** `index.defaults.*` and `index.<pass>.engine`: `index.*` and `connection`; a harness cannot run an index pass. */
+export function convertIndexEngines(out, conversion, retarget) {
+    const index = out.index;
+    if (!isRecord(index))
+        return;
+    const indexDefaults = index.defaults;
+    delete index.defaults;
+    if (isRecord(indexDefaults)) {
+        conversion.changed = true;
+        retarget(indexDefaults, "index.defaults.engine", false);
+        for (const key of ["connection", "model", "timeoutMs", "llm"])
+            if (indexDefaults[key] !== undefined)
+                index[key] ??= indexDefaults[key];
+    }
+    for (const [pass, value] of Object.entries(index))
+        if (pass !== "connection")
+            retarget(value, `index.${pass}.engine`, false);
+}

package/dist/core/config/convert-engines-shared.js

@@ -0,0 +1,40 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * What the pieces of the engines conversion share: the shapes they pass around and the
+ * few helpers more than one of them needs. See `convert-engines.ts`.
+ */
+import { isRecord } from "../common.js";
+import { normalizeExtraParamKey } from "../extra-params.js";
+import { inferenceWireFields } from "../llm-inference.js";
+export const str = (value) => (typeof value === "string" && value ? value : undefined);
+export const asDict = (value) => (isRecord(value) ? value : {});
+/**
+ * The request fields an old engine's (or a `models.json` entry's) inference
+ * becomes. The first-class settings win over `extraParams`: an `extraParams` key
+ * that names the same field as one of them (`temperature`, `maxTokens`/`max_tokens`,
+ * `enableThinking`, `reasoningEffort`, `chat_template_kwargs`) is dropped, with a
+ * note that names the key and not its value.
+ */
+export function wireFieldsOf(inference, where, notes) {
+    const { extraParams, ...settings } = inference;
+    const firstClass = inferenceWireFields(settings);
+    const taken = new Set(Object.keys(firstClass).map(normalizeExtraParamKey));
+    const extras = {};
+    for (const [key, value] of Object.entries(isRecord(extraParams) ? extraParams : {})) {
+        if (taken.has(normalizeExtraParamKey(key))) {
+            notes.push(`${where}: extraParams.${key} is dropped, because the setting it shadows takes precedence.`);
+        }
+        else {
+            extras[key] = value;
+        }
+    }
+    return { ...extras, ...firstClass };
+}
+/** `holder[key]` as an object, made on `holder` when it is not one yet. */
+export function objectAt(holder, key) {
+    if (!isRecord(holder[key]))
+        holder[key] = {};
+    return holder[key];
+}

package/dist/core/config/convert-engines.js

@@ -0,0 +1,300 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * The pre-0.10 `engines` / `defaults` config read as `connections` / `harnesses`.
+ *
+ * One pure function, two call sites: the loader runs it in memory on every read
+ * (`runConfigFilePipeline`) and `akm migrate apply` writes its result back.
+ * Whatever it cannot carry over is named in `notes` and dropped. One step per row of
+ * the migration table in `docs/reference/configuration.md`; `models.json` and the
+ * references in strategies, index passes and gates are folded in by their own modules.
+ */
+import { isRecord } from "../common.js";
+import { convertIndexEngines, dropJudgeEngine, improveStrategyDefault, moveStrategyExecution, retargeter, } from "./convert-engine-references.js";
+import { asDict, str, wireFieldsOf, } from "./convert-engines-shared.js";
+import { foldEngineModels, foldModelsOverlay } from "./convert-models-overlay.js";
+import { deepMergeConfig } from "./deep-merge.js";
+import { isEnvReference } from "./schema/primitives.js";
+const LLM_ENGINE_KEYS = new Set([
+    "kind",
+    "provider",
+    "endpoint",
+    "model",
+    "apiKey",
+    "apiKeyFile",
+    "temperature",
+    "maxTokens",
+    "timeoutMs",
+    "concurrency",
+    "supportsJsonSchema",
+    "extraParams",
+    "contextLength",
+    "enableThinking",
+    "reasoningEffort",
+]);
+const AGENT_ENGINE_KEYS = new Set([
+    "kind",
+    "platform",
+    "bin",
+    "args",
+    "workspace",
+    "model",
+    "agent",
+    "timeoutMs",
+    "llmEngine",
+]);
+const CARRIED = ["endpoint", "contextLength", "timeoutMs", "concurrency"];
+/**
+ * The environment variables an engine's key used to be read from without being
+ * named in config: `AKM_ENGINE_<NAME>_API_KEY` for any engine, and
+ * `AKM_LLM_API_KEY` for the engine `defaults.llmEngine` named.
+ */
+function implicitKeyVariables(name, defaults) {
+    const own = `AKM_ENGINE_${name.toUpperCase().replaceAll("-", "_")}_API_KEY`;
+    return name === str(defaults.llmEngine) ? [own, "AKM_LLM_API_KEY"] : [own];
+}
+// ── engines → connections / harnesses ────────────────────────────────────────
+/** `engines.<name>` with `kind: "agent"` and `platform: "opencode-sdk"`: akm's own runtime has no entry of its own. */
+function runtimeEngine(name, engine, converted, conversion) {
+    converted.runtimes.set(name, str(engine.llmEngine));
+    conversion.notes.push(`engines.${name}: opencode-sdk is akm's own runtime now, with no entry of its own; its model, timeout and workspace are dropped.`);
+}
+/** `engines.<name>` with `kind: "agent"`, any other platform: `harnesses.<name>`. */
+function agentEngineToHarness(name, engine, converted) {
+    const harness = { platform: engine.platform };
+    for (const key of ["bin", "args", "workspace", "agent", "timeoutMs"])
+        if (engine[key] !== undefined)
+            harness[key] = engine[key];
+    const model = str(engine.model);
+    if (model !== undefined)
+        converted.ownModelOf.push({ kind: "harnesses", engine: name, model });
+    converted.harnesses[name] = harness;
+}
+/**
+ * The key of an engine, on its connection: a `$VAR` is kept; a file, a literal or a secret reference cannot be
+ * (the key belongs in `credentials.json`); and with none written, the variable it used to be read from implicitly,
+ * when that one is set. When none is, the connection has no key, and a note says which variables 0.9 read.
+ */
+function carryEngineKey(name, engine, connection, defaults, env, converted, conversion) {
+    const apiKey = str(engine.apiKey);
+    if (apiKey !== undefined && isEnvReference(apiKey))
+        connection.apiKey = apiKey;
+    else if (apiKey !== undefined || engine.apiKeyFile !== undefined) {
+        converted.keyHolders.push({ engine: name, field: engine.apiKeyFile !== undefined ? "apiKeyFile" : "apiKey" });
+    }
+    else {
+        const variables = implicitKeyVariables(name, defaults);
+        const variable = variables.find((candidate) => env?.[candidate]?.trim());
+        if (variable !== undefined)
+            connection.apiKey = `$${variable}`;
+        else {
+            conversion.notes.push(`engines.${name}: it names no key, and ${variables.join(" or ")}, which it used to read when set, is not set here, so the connection has no key. If the endpoint needs one, set the variable and run \`akm setup --api-key-env <VARIABLE>\`, or store the key with \`akm setup\`.`);
+        }
+    }
+}
+/** `engines.<name>` with `kind: "llm"`: `connections.<name>`. */
+function llmEngineToConnection(name, engine, defaults, env, converted, conversion) {
+    const connection = {};
+    for (const key of CARRIED)
+        if (engine[key] !== undefined)
+            connection[key] = engine[key];
+    carryEngineKey(name, engine, connection, defaults, env, converted, conversion);
+    const model = str(engine.model);
+    if (model !== undefined)
+        converted.ownModelOf.push({ kind: "connections", engine: name, model });
+    if (engine.provider !== undefined) {
+        conversion.notes.push(`engines.${name}: provider is not a setting any more (akm does not branch on it); it is dropped.`);
+    }
+    if (engine.supportsJsonSchema === false) {
+        conversion.notes.push(`engines.${name}: supportsJsonSchema is not a setting any more; akm retries without a schema when the endpoint rejects one.`);
+    }
+    Object.assign(connection, wireFieldsOf({
+        temperature: engine.temperature,
+        maxTokens: engine.maxTokens,
+        extraParams: engine.extraParams,
+        enableThinking: engine.enableThinking,
+        reasoningEffort: engine.reasoningEffort,
+    }, `engines.${name}`, conversion.notes));
+    converted.connections[name] = connection;
+}
+function convertEngines(engines, defaults, env, conversion) {
+    const converted = {
+        connections: {},
+        harnesses: {},
+        runtimes: new Map(),
+        keyHolders: [],
+        ownModelOf: [],
+    };
+    for (const [name, engine] of Object.entries(engines)) {
+        if (!isRecord(engine))
+            continue;
+        const unknown = Object.keys(engine).filter((k) => !(engine.kind === "agent" ? AGENT_ENGINE_KEYS : LLM_ENGINE_KEYS).has(k));
+        if (unknown.length > 0)
+            conversion.notes.push(`engines.${name}: dropped ${unknown.join(", ")}, which akm does not read.`);
+        if (engine.kind !== "agent")
+            llmEngineToConnection(name, engine, defaults, env, converted, conversion);
+        else if (engine.platform === "opencode-sdk")
+            runtimeEngine(name, engine, converted, conversion);
+        else
+            agentEngineToHarness(name, engine, converted);
+    }
+    return converted;
+}
+// ── the defaults are the entries named `default` ─────────────────────────────
+/**
+ * The name each of `names` has once `from` is called `default`. An existing `default` moves aside to
+ * `legacy-default`, or the first `legacy-default-<n>` that nothing else (an engine, or an entry the file writes
+ * itself under `taken`) already has, so no two entries ever share a name and none is lost.
+ */
+function renameMap(names, taken, from) {
+    const moved = new Map();
+    if (from !== undefined && from !== "default") {
+        moved.set(from, "default");
+        if (names.includes("default")) {
+            const used = new Set([...names, ...taken]);
+            let aside = "legacy-default";
+            for (let n = 2; used.has(aside); n += 1)
+                aside = `legacy-default-${n}`;
+            moved.set("default", aside);
+        }
+    }
+    return (name) => moved.get(name) ?? name;
+}
+/** `defaults.llmEngine`, else `defaults.engine`: that connection is `default`; `defaults.engine` naming one of several harnesses: that harness is. */
+function nameDefaults(defaults, converted, conversion, written) {
+    const { connections, harnesses, runtimes, keyHolders } = converted;
+    const defaultEngine = str(defaults.engine);
+    const runtimeLlm = defaultEngine === undefined ? undefined : runtimes.get(defaultEngine);
+    const defaultConnection = [str(defaults.llmEngine), defaultEngine, runtimeLlm].find((n) => n !== undefined && n in connections);
+    const defaultHarness = defaultEngine !== undefined && defaultEngine in harnesses && Object.keys(harnesses).length > 1
+        ? defaultEngine
+        : undefined;
+    const connectionName = renameMap(Object.keys(connections), Object.keys(written.connections), defaultConnection);
+    const harnessName = renameMap(Object.keys(harnesses), Object.keys(written.harnesses), defaultHarness);
+    const renamed = (entries, name) => Object.fromEntries(Object.entries(entries).map(([engine, entry]) => [name(engine), entry]));
+    const named = {
+        connections: renamed(connections, connectionName),
+        harnesses: renamed(harnesses, harnessName),
+    };
+    const defaultHarnessName = "default" in named.harnesses
+        ? "default"
+        : Object.keys(named.harnesses).length === 1
+            ? Object.keys(named.harnesses)[0]
+            : undefined;
+    if (defaultHarnessName !== undefined && (defaultEngine === undefined || runtimes.has(defaultEngine))) {
+        conversion.notes.push(`Agent work ran on akm's own runtime${defaultEngine === undefined ? "" : ` (engines.${defaultEngine})`}; with the harness "${defaultHarnessName}" configured it now runs there. Remove that harness to keep agent work on akm's runtime.`);
+    }
+    for (const [kind, rename] of [
+        ["connections", connectionName],
+        ["harnesses", harnessName],
+    ]) {
+        const aside = rename("default");
+        if (aside === "default")
+            continue;
+        conversion.notes.push(`engines.default is now ${kind}.${aside}, and "default" names another engine: an engine: default key is rewritten by \`akm migrate apply\` where it can be, but a script or scheduled command that passes --engine default now reaches the new "default"; change it to the name ${aside}.`);
+    }
+    const target = (engine) => {
+        if (runtimes.has(engine)) {
+            const runtime = runtimes.get(engine);
+            return runtime !== undefined && runtime in connections ? { connection: connectionName(runtime) } : undefined;
+        }
+        if (engine in harnesses)
+            return { harness: harnessName(engine) };
+        if (engine in connections)
+            return { connection: connectionName(engine) };
+        return { connection: engine };
+    };
+    const keys = keyHolders.map(({ engine, field }) => ({
+        engine,
+        connection: connectionName(engine),
+        field,
+    }));
+    return { defaultConnection, defaultHarness, connectionName, harnessName, ...named, keys, target };
+}
+/** What the file writes under `connections` / `harnesses` itself, read with the converted entries: the written entry wins field by field. */
+function mergeWritten(out, naming) {
+    for (const [name, harness] of Object.entries(naming.harnesses)) {
+        if (harness.platform === name)
+            delete harness.platform;
+    }
+    return {
+        connections: deepMergeConfig(naming.connections, asDict(out.connections)),
+        harnesses: deepMergeConfig(naming.harnesses, asDict(out.harnesses)),
+    };
+}
+function ownModelsOf(converted, naming) {
+    const ownModels = { connections: new Map(), harnesses: new Map() };
+    for (const { kind, engine, model } of converted.ownModelOf) {
+        ownModels[kind].set(kind === "connections" ? naming.connectionName(engine) : naming.harnessName(engine), model);
+    }
+    return ownModels;
+}
+// ── the whole conversion ─────────────────────────────────────────────────────
+export function convertEngineConfig(raw, options = {}) {
+    const out = structuredClone(raw);
+    const engines = asDict(out.engines);
+    const defaults = asDict(out.defaults);
+    const conversion = {
+        notes: [],
+        changed: out.engines !== undefined || out.defaults !== undefined,
+    };
+    const converted = convertEngines(engines, defaults, options.env, conversion);
+    const naming = nameDefaults(defaults, converted, conversion, {
+        connections: asDict(out.connections),
+        harnesses: asDict(out.harnesses),
+    });
+    const merged = mergeWritten(out, naming);
+    const ownModels = ownModelsOf(converted, naming);
+    foldModelsOverlay(options.modelsOverlay, {
+        conversion,
+        merged,
+        ownModels,
+        written: { connections: asDict(out.connections), harnesses: asDict(out.harnesses) },
+        inherited: { connections: options.inherited?.connections ?? {}, harnesses: options.inherited?.harnesses ?? {} },
+        renamed: {
+            runtime: [...converted.runtimes.values()]
+                .filter((name) => name !== undefined && name in converted.connections)
+                .map((name) => naming.connectionName(name)),
+            connection: (engine) => (engine in converted.connections ? naming.connectionName(engine) : undefined),
+        },
+    });
+    foldEngineModels(merged, ownModels);
+    const retarget = retargeter(conversion, naming.target);
+    const improve = out.improve;
+    if (isRecord(improve))
+        moveStrategyExecution(improve, conversion, retarget);
+    improveStrategyDefault(out, defaults, improve);
+    dropJudgeEngine(out, conversion);
+    convertIndexEngines(out, conversion, retarget);
+    // Assemble, keeping the file's key order.
+    const config = {};
+    let placed = false;
+    for (const [key, value] of Object.entries(out)) {
+        if (key === "defaults")
+            continue;
+        if (key !== "engines" && key !== "connections" && key !== "harnesses") {
+            config[key] = value;
+        }
+        else if (!placed) {
+            placed = true;
+            if (Object.keys(merged.connections).length > 0)
+                config.connections = merged.connections;
+            if (Object.keys(merged.harnesses).length > 0)
+                config.harnesses = merged.harnesses;
+        }
+    }
+    const targets = {};
+    for (const name of Object.keys(engines).filter((engine) => isRecord(engines[engine]))) {
+        const became = naming.target(name);
+        if (became !== undefined)
+            targets[name] = became;
+    }
+    return {
+        config: conversion.changed ? config : raw,
+        notes: conversion.notes,
+        changed: conversion.changed,
+        keys: naming.keys,
+        targets,
+    };
+}

package/dist/core/config/convert-models-overlay.js

@@ -0,0 +1,137 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `models.json`, and an engine's own `model`, folded into the `models` of the connections
+ * and harnesses the engines became. See `convert-engines.ts`.
+ */
+import { getHarness } from "../../integrations/harnesses/index.js";
+import { isRecord } from "../common.js";
+import { str, wireFieldsOf } from "./convert-engines-shared.js";
+import { modelForEveryAlias } from "./model-aliases.js";
+const allAliases = (model) => model === undefined ? undefined : modelForEveryAlias(model);
+/** An overlay entry as a model entry: the bare name, or `{ model, ...fields }` when it sets more. */
+function modelEntry(model, fields) {
+    return Object.keys(fields).length > 0 ? { model, ...fields } : model;
+}
+// ── models.json folds into the models of what it named ───────────────────────
+/** The models of `entry`, made on it when it has none yet. */
+function modelsOf(entry) {
+    entry.models ??= {};
+    return entry.models;
+}
+const hasModel = (entry, alias) => isRecord(entry) && isRecord(entry.models) && alias in entry.models;
+/**
+ * The overlay's rows: one per alias and column, the runtime's column first (it is the weakest, naming OpenCode's own
+ * models), then a connection's own, then `*`, which fills what is left. The flat shorthand is the `*` column.
+ */
+function overlayRows(modelsOverlay) {
+    const overlay = isRecord(modelsOverlay) && isRecord(modelsOverlay.aliases) ? modelsOverlay.aliases : {};
+    const rows = Object.entries(overlay).flatMap(([alias, columns]) => {
+        if (!isRecord(columns))
+            return [];
+        const flat = Object.fromEntries(Object.entries(columns).filter(([k]) => k === "model" || k === "inference" || k === "engine"));
+        const perColumn = Object.entries(columns).filter(([k]) => !(k in flat));
+        return [...perColumn, ...(Object.keys(flat).length > 0 ? [["*", flat]] : [])].map(([column, profile]) => ({
+            alias,
+            column,
+            profile,
+        }));
+    });
+    const rank = (column) => (column === "opencode-sdk" ? 0 : column === "*" ? 2 : 1);
+    return rows.sort((a, b) => rank(a.column) - rank(b.column));
+}
+/**
+ * `models.json`: an alias is set by, nearest first, the config's own `models`, models.json's column for that
+ * connection or harness, models.json's `*` column (and the flat shorthand, which is that), the engine's own model.
+ */
+export function foldModelsOverlay(modelsOverlay, fold) {
+    const { conversion, merged, written, inherited, ownModels, renamed } = fold;
+    const { notes } = conversion;
+    const mergedConnections = merged.connections;
+    const mergedHarnesses = merged.harnesses;
+    const inheritedConnections = inherited.connections;
+    const inheritedHarnesses = inherited.harnesses;
+    const writtenConnections = written.connections;
+    const writtenHarnesses = written.harnesses;
+    /** Whether the config itself, the file or its base, already names a model for the alias. */
+    const configNames = (own, base, name, alias) => hasModel(own[name], alias) || hasModel(base[name], alias);
+    const platformOf = (name) => String((mergedHarnesses[name] ?? inheritedHarnesses[name])?.platform ?? name);
+    let folded = false;
+    for (const { alias, column, profile } of overlayRows(modelsOverlay)) {
+        const p = typeof profile === "string" ? { model: profile } : isRecord(profile) ? profile : {};
+        const { effort, ...portable } = (isRecord(p.inference) ? p.inference : {});
+        const where = `models.json ${alias}.${column === "*" ? "(all)" : column}`;
+        const wire = wireFieldsOf({ ...portable, reasoningEffort: portable.reasoningEffort ?? effort }, where, notes);
+        if (p.engine !== undefined) {
+            notes.push(`${where}: an engine indirection is not carried over.`);
+            continue;
+        }
+        const candidates = column === "*"
+            ? [...new Set([...Object.keys(mergedConnections), ...Object.keys(inheritedConnections)])]
+            : column === "opencode-sdk"
+                ? [...renamed.runtime]
+                : renamed.connection(column) !== undefined
+                    ? [renamed.connection(column)]
+                    : column in writtenConnections || column in inheritedConnections
+                        ? [column]
+                        : [];
+        const harnessNamed = [...new Set([...Object.keys(mergedHarnesses), ...Object.keys(inheritedHarnesses)])].filter((name) => platformOf(name) === column);
+        if (candidates.length === 0 && harnessNamed.length === 0) {
+            notes.push(`${where}: names no configured connection or harness, so it is not carried over.`);
+            continue;
+        }
+        // The config's own choice stands, and `*` leaves what an explicit column already set.
+        const connectionNames = candidates.filter((name) => !configNames(writtenConnections, inheritedConnections, name, alias) &&
+            !(column === "*" && hasModel(mergedConnections[name], alias)));
+        const harnessNames = harnessNamed.filter((name) => !configNames(writtenHarnesses, inheritedHarnesses, name, alias));
+        if (connectionNames.length === 0 && harnessNames.length === 0) {
+            // Only the config's own choice is worth a note; an explicit column that came first is the overlay's own.
+            const keptByConfig = candidates.some((name) => configNames(writtenConnections, inheritedConnections, name, alias)) ||
+                harnessNamed.some((name) => configNames(writtenHarnesses, inheritedHarnesses, name, alias));
+            if (keptByConfig)
+                notes.push(`${where}: the config already names a model for it, so it is not carried over.`);
+            continue;
+        }
+        for (const name of connectionNames) {
+            const current = mergedConnections[name]?.models;
+            const existing = current?.[alias];
+            const model = str(p.model) ?? str(isRecord(existing) ? existing.model : existing) ?? ownModels.connections.get(name);
+            if (model === undefined)
+                continue;
+            // A connection only the base defines gets a partial entry here; the base completes it.
+            mergedConnections[name] ??= {};
+            modelsOf(mergedConnections[name])[alias] = modelEntry(model, wire);
+            folded = true;
+        }
+        for (const name of harnessNames) {
+            const model = str(p.model) ?? str(getHarness(platformOf(name))?.models?.[alias]);
+            if (model === undefined)
+                continue;
+            mergedHarnesses[name] ??= {};
+            modelsOf(mergedHarnesses[name])[alias] = model;
+            folded = true;
+            if (Object.keys(wire).length > 0)
+                notes.push(`${where}: a harness takes the model only; the inference settings are not carried over.`);
+        }
+    }
+    if (folded)
+        conversion.changed = true;
+}
+/** An engine's `model`: every alias nothing else named is that model, on the entry the engine became. */
+export function foldEngineModels(merged, ownModels) {
+    for (const [kind, entries] of [
+        ["connections", merged.connections],
+        ["harnesses", merged.harnesses],
+    ]) {
+        for (const [name, model] of ownModels[kind]) {
+            const entry = entries[name];
+            if (!isRecord(entry))
+                continue;
+            for (const [alias, value] of Object.entries(allAliases(model) ?? {})) {
+                if (!hasModel(entry, alias))
+                    modelsOf(entry)[alias] = value;
+            }
+        }
+    }
+}