akm-cli 0.10.261012-beta → 0.10.261014-beta

package/dist/core/config/credentials.js

@@ -0,0 +1,304 @@
+// 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/.
+/**
+ * API keys akm holds for the user: `<configDir>/credentials.json` (0600).
+ *
+ *     { "connections": { "<name>": { "key": "…", "endpoint": "…" } },
+ *       "services":    { "embedding": { "key": "…", "endpoint": "…" },
+ *                        "curateRerank": { … } } }
+ *
+ * A key is stored for one endpoint and is read for that endpoint alone: the
+ * entry records the endpoint it was stored for, and a block whose endpoint is
+ * now another gets no key, with a word saying so. Only the connections this
+ * host's own config file defines have a stored key: one that only an `extends`
+ * base defines gets none, whatever the store holds under its name. A connection's name and a
+ * service's slot are different namespaces, so a connection called `embedding`
+ * and the embedding service hold different keys. A block whose `apiKey` is a
+ * `$VAR` reference reads that variable and never touches this file. The bundle's
+ * `secrets/` store is for secrets the user's own agents need and has nothing to
+ * do with these.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { isRecord, writeFileAtomic } from "../common.js";
+import { sameEndpoint } from "../endpoint-url.js";
+import { ConfigError } from "../errors.js";
+import { getConfigDir } from "../paths.js";
+import { collectSensitiveValues, redactUrlCredentials } from "../redaction.js";
+import { warnOnce } from "../warn.js";
+import { isInheritedConnection } from "./config.js";
+import { copyToConfigBackups } from "./config-io.js";
+import { envReferenceName, isEnvReference } from "./schema/primitives.js";
+const NAMESPACES = ["connections", "services"];
+function storePath() {
+    return path.join(getConfigDir(), "credentials.json");
+}
+function namespaceOf(slot) {
+    return "connection" in slot
+        ? { group: "connections", name: slot.connection }
+        : { group: "services", name: slot.service };
+}
+function describeSlot(slot) {
+    return "connection" in slot ? `connection "${slot.connection}"` : `the ${slot.service} service`;
+}
+/** The stored entries; an absent file holds none. */
+function readStore() {
+    let text;
+    try {
+        text = fs.readFileSync(storePath(), "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        return code === "ENOENT"
+            ? { entries: {} }
+            : { problem: `${storePath()} cannot be read (${code ?? "unknown error"})` };
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (isRecord(parsed))
+            return { entries: parsed };
+    }
+    catch {
+        // Falls through: not JSON is not a JSON object.
+    }
+    return { problem: `${storePath()} is not a JSON object` };
+}
+function writeStore(entries) {
+    fs.mkdirSync(path.dirname(storePath()), { recursive: true, mode: 0o700 });
+    writeFileAtomic(storePath(), `${JSON.stringify(entries, null, 2)}\n`, 0o600);
+}
+/** The group of entries (`connections` or `services`) a store holds; anything else there is not one. */
+function groupOf(entries, group) {
+    const held = entries[group];
+    return isRecord(held) ? held : {};
+}
+/** Whether a stored value is the current shape of an entry. */
+function isStoredCredential(value) {
+    return isRecord(value) && typeof value.key === "string" && typeof value.endpoint === "string";
+}
+/**
+ * The stored entry for `slot`, if the store has one in the current shape. One
+ * the store has in any other shape (the flat `{ "<name>": "<key>" }` an earlier
+ * build wrote, which names no endpoint) is named once and ignored: `akm migrate
+ * apply` files it under the endpoint it belongs to.
+ */
+export function storedCredential(slot) {
+    const store = readStore();
+    if ("problem" in store) {
+        warnOnce(`credentials:unusable:${storePath()}`, `${store.problem}; ignoring it.`);
+        return undefined;
+    }
+    const { group, name } = namespaceOf(slot);
+    const held = groupOf(store.entries, group)[name];
+    if (held === undefined) {
+        const flat = store.entries[name];
+        if (typeof flat === "string") {
+            warnOnce(`credentials:flat:${storePath()}:${name}`, `${storePath()}: the key "${name}" is in the older form, which names no endpoint, so it is not used; \`akm migrate apply\` files it under the endpoint it belongs to.`);
+        }
+        return undefined;
+    }
+    if (!isStoredCredential(held)) {
+        warnOnce(`credentials:malformed:${storePath()}:${group}:${name}`, `${storePath()}: the entry for ${describeSlot(slot)} is not { "key": "…", "endpoint": "…" }; ignoring it.`);
+        return undefined;
+    }
+    return held;
+}
+/**
+ * The key stored for `slot` and `endpoint`. A key stored for another endpoint is
+ * not read: it is named once, without its value, and the block goes without.
+ * `storedKey` is a connection's eligibility already decided (a runner carries it);
+ * absent, the config on this host decides now.
+ */
+export function readCredential(slot, endpoint, storedKey) {
+    if ("connection" in slot) {
+        const eligible = storedKey ?? !isInheritedConnection(slot.connection);
+        if (!eligible)
+            return undefined;
+    }
+    const held = storedCredential(slot);
+    if (!held)
+        return undefined;
+    if (!sameEndpoint(held.endpoint, endpoint)) {
+        const shownHeld = redactUrlCredentials(held.endpoint);
+        const shownNow = redactUrlCredentials(endpoint);
+        warnOnce(`credentials:endpoint:${storePath()}:${describeSlot(slot)}:${shownHeld}:${shownNow}`, `The key stored for ${describeSlot(slot)} belongs to ${shownHeld}, not ${shownNow}, so it is not sent there. Store a key for the new endpoint with \`akm setup\`.`);
+        return undefined;
+    }
+    return held.key || undefined;
+}
+function writableStore() {
+    const store = readStore();
+    if ("problem" in store)
+        throw new ConfigError(`${store.problem}; refusing to overwrite it.`, "INVALID_CONFIG_FILE");
+    return store.entries;
+}
+/**
+ * Store `key` for `slot` and `endpoint`, keeping every other entry as it is. A root
+ * `connections` or `services` that is not an object is a key of the older flat form
+ * (a connection of that name) in the namespace's place: it is kept, and the write stops,
+ * because the write would replace it. `akm migrate apply` files it under its endpoint.
+ */
+export function writeCredential(slot, key, endpoint) {
+    const entries = writableStore();
+    const { group, name } = namespaceOf(slot);
+    const root = entries[group];
+    if (root !== undefined && !isRecord(root)) {
+        throw new ConfigError(`${storePath()}: "${group}" holds ${typeof root === "string" ? "a key in the older form" : "something that is not an object"}, which is where the ${group} are stored, so ${describeSlot(slot)} cannot be stored beside it; refusing to overwrite it. ${typeof root === "string" ? "`akm migrate apply` files it under its endpoint; then store this key again." : "Fix the file, then store this key again."}`, "INVALID_CONFIG_FILE");
+    }
+    writeStore({ ...entries, [group]: { ...groupOf(entries, group), [name]: { key, endpoint } } });
+}
+/** The entries the store holds in the current shape, by slot, whatever endpoint each is stored for. */
+export function storedCredentials() {
+    const store = readStore();
+    if ("problem" in store)
+        return [];
+    return NAMESPACES.flatMap((group) => Object.entries(groupOf(store.entries, group)).flatMap(([name, held]) => isStoredCredential(held)
+        ? [
+            {
+                slot: group === "connections" ? { connection: name } : { service: name },
+                credential: held,
+            },
+        ]
+        : []));
+}
+/**
+ * Every migration into a credential slot asks this one question. An empty slot is
+ * `free`; one holding exactly this key for this endpoint is `same` (filing it again
+ * changes nothing); anything else, a malformed entry included, is `different`, and
+ * is never replaced: the migration leaves both and says so. `ahead` is the entry the
+ * same migration has already planned for the slot, which stands in for the store's.
+ */
+export function slotStanding(slot, key, endpoint, ahead) {
+    let held = ahead;
+    if (held === undefined) {
+        const store = readStore();
+        // An unusable store is not a conflict: it refuses every write, which stops the migration with nothing lost.
+        if ("problem" in store)
+            return "free";
+        const { group, name } = namespaceOf(slot);
+        held = groupOf(store.entries, group)[name];
+    }
+    if (held === undefined)
+        return "free";
+    return isStoredCredential(held) && held.key === key && sameEndpoint(held.endpoint, endpoint) ? "same" : "different";
+}
+/**
+ * File every key the store holds in the older flat `{ "<name>": "<key>" }` form under
+ * the endpoint of the block it belongs to, as `endpointOf` says: a name that is a
+ * connection's, or `curateRerank`, or `embedding` (the service's, or a connection
+ * called that: one of the two must have an endpoint, or it is not filed). `pending` is
+ * what the same migration is about to file in the current form, which a flat key is
+ * measured against like the store's own entries ({@link slotStanding}): a slot that
+ * already holds the same key for the same endpoint just drops the older entry, and one
+ * that holds anything else keeps the older entry, with a note. An entry that cannot be
+ * filed stays as it is, and a note says why. Writes only when `apply`, after copying
+ * the store to the config-backups directory (`backupPath`).
+ */
+export function fileFlatCredentials(endpointOf, apply, pending = []) {
+    const store = readStore();
+    if ("problem" in store)
+        return { filed: [], notes: [`${store.problem}; its keys were not filed.`] };
+    const entries = { ...store.entries };
+    const filed = [];
+    const notes = [];
+    // A key called `connections` or `services` is told from the namespace of that name by its shape: a string. It sits
+    // where the namespace goes, so it is filed first, and until it is, no other key can be filed into that namespace.
+    const rank = (name) => {
+        const index = NAMESPACES.indexOf(name);
+        return index < 0 ? NAMESPACES.length : index;
+    };
+    for (const name of Object.keys(store.entries).sort((a, b) => rank(a) - rank(b))) {
+        const value = store.entries[name];
+        if (typeof value !== "string")
+            continue;
+        const slots = name === "curateRerank"
+            ? [{ service: "curateRerank" }]
+            : name === "embedding"
+                ? [{ service: "embedding" }, { connection: name }]
+                : [{ connection: name }];
+        const homes = slots.flatMap((slot) => {
+            const endpoint = endpointOf(slot);
+            return endpoint === undefined ? [] : [{ slot, endpoint }];
+        });
+        const home = homes[0];
+        if (homes.length !== 1 || home === undefined) {
+            notes.push(homes.length > 1
+                ? `credentials.json: the key "${name}" could belong to the embedding service or to the connection of that name; store it again with \`akm setup\`. It stays as it is.`
+                : `credentials.json: the key "${name}" belongs to no block this config gives an endpoint, so it cannot be bound to one. It stays as it is.`);
+            continue;
+        }
+        const { group, name: slotName } = namespaceOf(home.slot);
+        if (name !== group && entries[group] !== undefined && !isRecord(entries[group])) {
+            notes.push(`credentials.json: the key "${name}" cannot be filed while the key "${group}" in the older form holds the place the ${group} go. It stays as it is; give the block called "${group}" an endpoint so it can be filed first, or remove it.`);
+            continue;
+        }
+        const ahead = pending.find((move) => JSON.stringify(move.slot) === JSON.stringify(home.slot));
+        const standing = slotStanding(home.slot, value, home.endpoint, ahead && { key: ahead.value, endpoint: ahead.endpoint });
+        if (standing === "different") {
+            notes.push(`credentials.json: ${describeSlot(home.slot)} already holds a different key or endpoint than the older entry "${name}"; neither is replaced. Remove the older entry when the stored one is the key you want.`);
+            continue;
+        }
+        if (standing === "free" || name === group) {
+            entries[group] = { ...groupOf(entries, group), [slotName]: { key: value, endpoint: home.endpoint } };
+        }
+        // The key called like its own namespace has just become that namespace's child, in the same place.
+        if (name !== group)
+            delete entries[name];
+        filed.push(name);
+        notes.push(standing === "free"
+            ? `credentials.json: the key "${name}" is filed for ${describeSlot(home.slot)} at ${redactUrlCredentials(home.endpoint)}.`
+            : `credentials.json: the key "${name}" is already stored for ${describeSlot(home.slot)} at ${redactUrlCredentials(home.endpoint)}; the older entry is removed.`);
+    }
+    if (!apply || filed.length === 0)
+        return { filed, notes };
+    const backupPath = copyToConfigBackups(storePath(), (stamp) => `credentials.json.${stamp}`);
+    writeStore(entries);
+    return { filed, notes, backupPath };
+}
+/**
+ * The key of the block stored in `slot`, whose config `apiKey` is `apiKey` and
+ * whose endpoint is `endpoint`: the variable it references, else the key stored
+ * for that endpoint. An unset variable is named once and sends no key. `quiet`
+ * is for callers that only collect values to redact; `storedKey` is as for
+ * {@link readCredential}.
+ */
+export function resolveApiKey(apiKey, slot, endpoint, env = process.env, quiet = false, storedKey) {
+    const variable = apiKey === undefined ? undefined : envReferenceName(apiKey);
+    if (variable === undefined)
+        return readCredential(slot, endpoint, storedKey);
+    const value = env[variable]?.trim();
+    if (!value && !quiet) {
+        warnOnce(`credentials:env-unset:${variable}`, `Environment variable ${variable} referenced by an apiKey is unset or empty; requests are sent without a key.`);
+    }
+    return value || undefined;
+}
+/**
+ * The `$VAR` reference an `apiKey` holds. Anything else in that field is a key
+ * the user left in the file, which akm never reads or sends and never passes on.
+ */
+export function apiKeyReference(apiKey) {
+    return apiKey !== undefined && isEnvReference(apiKey) ? apiKey : undefined;
+}
+/**
+ * Every key akm could send or has been given, for redaction: whatever the store
+ * holds, the variables the config's blocks reference, and any key left in the
+ * file as written.
+ */
+export function collectCredentialValues(config, env = process.env) {
+    const blocks = [
+        ...Object.values(config.connections ?? {}),
+        config.embedding,
+        config.search?.curateRerank,
+    ];
+    return collectSensitiveValues([
+        ...storedCredentials().map(({ credential }) => credential.key),
+        ...blocks.flatMap((block) => {
+            const variable = block?.apiKey === undefined ? undefined : envReferenceName(block.apiKey);
+            return [
+                variable === undefined ? undefined : env[variable]?.trim(),
+                apiKeyReference(block?.apiKey) === undefined ? block?.apiKey : undefined,
+            ];
+        }),
+    ]);
+}

package/dist/core/config/engine-semantics.js

@@ -16,8 +16,8 @@ export const REMOVED_IMPROVE_STRATEGY_NAMES = [
     "proactive-maintenance",
 ];
 /**
- * The improve processes that use an engine. Triage's engine is its judgment's;
- * each of the others makes the process's own model calls.
+ * The improve processes that make model calls, so each runs on a connection or
+ * harness. Triage's is its judgment's; each of the others makes the process's own calls.
  */
 export const IMPROVE_ENGINE_PROCESSES = [
     "reflect",
@@ -28,5 +28,5 @@ export const IMPROVE_ENGINE_PROCESSES = [
     "validation",
     "triage",
 ];
-/** Every improve process, in plan order: the engine processes and `proactiveMaintenance`, which uses none. */
+/** Every improve process, in plan order: the model-calling processes and `proactiveMaintenance`, which makes no model call. */
 export const IMPROVE_PROCESS_NAMES = [...IMPROVE_ENGINE_PROCESSES, "proactiveMaintenance"];

package/dist/core/config/migrate-keys.js

@@ -0,0 +1,222 @@
+// 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/.
+/**
+ * `akm migrate apply`'s key step. akm reads a key from a `$VAR` reference or
+ * from `credentials.json`, nowhere else. The keys a config still holds in any
+ * other form are read once, filed in `credentials.json` for the block they
+ * belong to (a connection, or the `embedding` or `curateRerank` service) and the
+ * endpoint that block names, and removed from the document:
+ *
+ *   - an engine's `apiKeyFile`, a literal `apiKey` or a `${secrets/...}` one,
+ *     which the conversion to a connection cannot carry;
+ *   - the same literal or secret-store `apiKey` on a connection, `embedding` or
+ *     `search.curateRerank` that the file already says in the current form.
+ *
+ * A key that cannot be read, whose block names no endpoint to file it for, whose
+ * engine wrote it for another endpoint than the connection now names (the file's
+ * current-form entries overlay the converted engine), or whose slot
+ * `credentials.json` already holds a different key or endpoint for, is not moved. It stays in the file: on the block that held
+ * it, or, for an engine's `apiKey`, put back on the connection as `apiKey`
+ * exactly as it was, so the rewrite never leaves it in the backups alone (akm
+ * ignores a key held there, with a warning, until it is moved). An engine's
+ * `apiKeyFile` is the exception: it names a file, not a key, and a connection
+ * cannot hold it (an unowned key is sent as a request field), so a note names
+ * the path. A note names the key's place and its entry, never its value.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { isRecord } from "../common.js";
+import { sameEndpoint } from "../endpoint-url.js";
+import { redactUrlCredentials } from "../redaction.js";
+import { isSecretRefToken } from "../ref-token.js";
+import { slotStanding } from "./credentials.js";
+import { isEnvReference } from "./schema/primitives.js";
+/** An `apiKeyFile`'s key: the file's contents less one trailing newline, `~` expanded as it always was. */
+function readKeyFile(file) {
+    try {
+        const expanded = file.startsWith("~") ? path.join(os.homedir(), file.slice(1)) : file;
+        return fs.readFileSync(expanded, "utf8").replace(/\r?\n$/, "") || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A key held in the config itself: the literal, or the secret it references. */
+function heldValue(value, options) {
+    if (!isSecretRefToken(value))
+        return value;
+    try {
+        return options.resolveSecretRef?.(value) || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The keys of the converted document that are not `$VAR` references. */
+function documentCandidates(config, options) {
+    const blocks = [];
+    if (isRecord(config.connections)) {
+        for (const [name, block] of Object.entries(config.connections)) {
+            if (isRecord(block))
+                blocks.push({ name, slot: { connection: name }, from: `connections.${name}.apiKey`, block });
+        }
+    }
+    const search = isRecord(config.search) ? config.search : {};
+    if (isRecord(config.embedding)) {
+        blocks.push({
+            name: "embedding",
+            slot: { service: "embedding" },
+            from: "embedding.apiKey",
+            block: config.embedding,
+        });
+    }
+    if (isRecord(search.curateRerank)) {
+        blocks.push({
+            name: "curateRerank",
+            slot: { service: "curateRerank" },
+            from: "search.curateRerank.apiKey",
+            block: search.curateRerank,
+        });
+    }
+    return blocks.flatMap(({ name, slot, from, block }) => {
+        const endpoint = typeof block.endpoint === "string" ? block.endpoint : undefined;
+        const found = [];
+        const apiKey = block.apiKey;
+        if (typeof apiKey === "string" && !isEnvReference(apiKey)) {
+            found.push({
+                name,
+                slot,
+                endpoint,
+                from,
+                read: () => heldValue(apiKey, options),
+                source: isSecretRefToken(apiKey) ? "the secret store reference" : "the literal key",
+                remove: () => {
+                    delete block.apiKey;
+                },
+                stays: "in the file",
+            });
+        }
+        // A key file an earlier run could not read is still named here, so a later run can move its key.
+        const keyFile = block.apiKeyFile;
+        if (typeof keyFile === "string" && "connection" in slot) {
+            found.push({
+                name,
+                slot,
+                endpoint,
+                from: from.replace(/apiKey$/, "apiKeyFile"),
+                read: () => readKeyFile(keyFile),
+                source: `its key file ${keyFile}`,
+                remove: () => {
+                    delete block.apiKeyFile;
+                },
+                stays: "in the file",
+            });
+        }
+        return found;
+    });
+}
+/** The endpoint the document gives the block that `slot` stands for, if it gives one. */
+export function documentEndpoint(config, slot) {
+    const search = isRecord(config.search) ? config.search : {};
+    const block = "connection" in slot
+        ? isRecord(config.connections)
+            ? config.connections[slot.connection]
+            : undefined
+        : slot.service === "embedding"
+            ? config.embedding
+            : search.curateRerank;
+    return isRecord(block) && typeof block.endpoint === "string" ? block.endpoint : undefined;
+}
+/** The keys the conversion could not carry from an engine, read from the original document. */
+function engineCandidates(original, converted, config, options) {
+    const engines = isRecord(original.engines) ? original.engines : {};
+    return converted.keys.flatMap(({ engine, connection, field }) => {
+        const source = isRecord(engines[engine]) ? engines[engine] : {};
+        const held = source[field];
+        if (typeof held !== "string")
+            return [];
+        const owner = typeof source.endpoint === "string" ? source.endpoint : undefined;
+        if (field === "apiKeyFile") {
+            return [
+                {
+                    name: connection,
+                    slot: { connection },
+                    endpoint: documentEndpoint(config, { connection }),
+                    owner,
+                    from: `engines.${engine}.${field}`,
+                    read: () => readKeyFile(held),
+                    source: `its key file ${held}`,
+                    restore: () => {
+                        const block = isRecord(config.connections) ? config.connections[connection] : undefined;
+                        if (isRecord(block))
+                            block.apiKeyFile = held;
+                    },
+                    stays: "on the connection as apiKeyFile",
+                },
+            ];
+        }
+        return [
+            {
+                name: connection,
+                slot: { connection },
+                endpoint: documentEndpoint(config, { connection }),
+                owner,
+                from: `engines.${engine}.${field}`,
+                read: () => heldValue(held, options),
+                source: isSecretRefToken(held) ? `the secret store reference ${held}` : "the literal key",
+                restore: () => {
+                    const block = isRecord(config.connections) ? config.connections[connection] : undefined;
+                    if (isRecord(block))
+                        block.apiKey = held;
+                },
+                stays: "on the connection as apiKey",
+            },
+        ];
+    });
+}
+export function planKeyMoves(original, converted, options = {}) {
+    const config = structuredClone(converted.config);
+    const planned = new Map();
+    const moves = [];
+    const notes = [];
+    for (const candidate of [
+        ...engineCandidates(original, converted, config, options),
+        ...documentCandidates(config, options),
+    ]) {
+        const stays = ` It stays ${candidate.stays}.`;
+        const { owner } = candidate;
+        if (owner !== undefined && candidate.endpoint !== undefined && !sameEndpoint(owner, candidate.endpoint)) {
+            candidate.restore?.();
+            notes.push(`${candidate.from}: this key was written for ${redactUrlCredentials(owner)}, and the file now gives "${candidate.name}" ${redactUrlCredentials(candidate.endpoint)}, so no key moves and it is not sent there.${stays} Store a key for the new endpoint with \`akm setup\`.`);
+            continue;
+        }
+        const value = candidate.read();
+        if (value === undefined) {
+            candidate.restore?.();
+            notes.push(`${candidate.from}: ${candidate.source} could not be read, so no key moves and this is still to do.${stays} A later \`akm migrate apply\` moves it once it can be read.`);
+            continue;
+        }
+        const { endpoint } = candidate;
+        if (endpoint === undefined) {
+            candidate.restore?.();
+            notes.push(`${candidate.from}: the block names no endpoint of its own, so its key cannot be filed for one and no key moves.${stays} Store it for the endpoint that serves it with \`akm setup\`.`);
+            continue;
+        }
+        const slotKey = JSON.stringify(candidate.slot);
+        const earlier = planned.get(slotKey);
+        const standing = slotStanding(candidate.slot, value, endpoint, earlier && { key: earlier.value, endpoint: earlier.endpoint });
+        if (standing === "different") {
+            candidate.restore?.();
+            notes.push(`${candidate.from}: credentials.json already holds a different key or endpoint for "${candidate.name}"; it is not replaced.${stays}`);
+            continue;
+        }
+        const move = { slot: candidate.slot, endpoint, name: candidate.name, value, from: candidate.from };
+        planned.set(slotKey, move);
+        moves.push(move);
+        notes.push(`${candidate.from}: its key moves to credentials.json for "${candidate.name}" at ${redactUrlCredentials(endpoint)}.`);
+        candidate.remove?.();
+    }
+    return { config, moves, notes };
+}

package/dist/core/config/model-aliases.js

@@ -0,0 +1,37 @@
+// 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 model aliases akm itself speaks: a call asks for a model by one of these
+ * (or by an exact name), and each connection or harness says which of its own
+ * models answers to them.
+ */
+export const STANDARD_ALIASES = ["fast", "balanced", "reasoning"];
+/**
+ * The alias each kind of call asks for when nothing nearer (an asset, a process,
+ * a flag) names a model. It is the farthest layer of the call.
+ */
+export const SHIPPED_ALIAS = {
+    /** Improve's passes: reflect, distill, consolidate, memory inference, validation. */
+    improve: "fast",
+    /** Judges: the reflect and distill quality gates, the triage judgment, a workflow gate. */
+    judge: "balanced",
+    /** Agent work: `akm agent`, `command run`, `proposal new`, task dispatch, workflow agent units. */
+    agent: "balanced",
+    extract: "fast",
+    enrich: "fast",
+    /** The index passes. */
+    index: "fast",
+};
+/** One model answering to every standard alias: what a connection with a single model has. */
+export function modelForEveryAlias(model) {
+    return { fast: model, balanced: model, reasoning: model };
+}
+/** The model name an alias entry holds. */
+export function entryModel(entry) {
+    return typeof entry === "string" ? entry : entry.model;
+}
+/** The entry for `entry` once it names `model`: an entry with request fields keeps them. */
+export function entryWithModel(entry, model) {
+    return typeof entry === "object" ? { ...entry, model } : model;
+}

package/dist/core/config/models-file.js

@@ -0,0 +1,34 @@
+// 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 user's `models.json` (retired): `<configDir>/models.json`, an alias to
+ * model table per engine. It is read, in memory, as part of the conversion of
+ * the `engines` form ({@link convertEngineConfig}); `akm migrate apply` moves it
+ * out of the config directory once its aliases are folded into the config.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getConfigDir } from "../paths.js";
+import { copyToConfigBackups } from "./config-io.js";
+function modelsFilePath() {
+    return path.join(getConfigDir(), "models.json");
+}
+/** The user's `models.json`, parsed; absent or unreadable is no overlay. */
+export function readModelsFile() {
+    try {
+        return JSON.parse(fs.readFileSync(modelsFilePath(), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function modelsFileExists() {
+    return fs.existsSync(modelsFilePath());
+}
+/** Move `models.json` to `<cacheDir>/config-backups/models.json.<timestamp>` and return where it went. */
+export function retireModelsFile(now = new Date()) {
+    const target = copyToConfigBackups(modelsFilePath(), (stamp) => `models.json.${stamp}`, now);
+    fs.rmSync(modelsFilePath());
+    return target;
+}

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

@@ -0,0 +1,53 @@
+// 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 engine names of the retired `engines` form became, kept in the data
+ * directory (`migrate/engine-targets.json`) after `akm migrate apply` has rewritten
+ * the config. The conversion renames the engine `defaults` named to `default` and
+ * moves an old `default` aside, so an `engine:` selector that is still in a file the
+ * migration has not rewritten (a read-only bundle, a block it could not splice) keeps
+ * its meaning only if the old names outlive the config that had them. The migrator
+ * writes and removes this file; the resolver of `engine:` selectors reads it
+ * ({@link retiredEngineTargets}); nothing else does.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { isRecord } from "../common.js";
+import { getDataDir } from "../paths.js";
+function rememberedPath() {
+    return path.join(getDataDir(), "migrate", "engine-targets.json");
+}
+/** An old engine name's entry, when it is `{ "connection": "<name>" }` or `{ "harness": "<name>" }`. */
+function targetOf(value) {
+    if (!isRecord(value))
+        return undefined;
+    if (typeof value.connection === "string" && value.connection)
+        return { connection: value.connection };
+    if (typeof value.harness === "string" && value.harness)
+        return { harness: value.harness };
+    return undefined;
+}
+/** The names an earlier run's config step recorded; a file that is not a name map, or an entry that is not a target, holds none. */
+export function rememberedEngineTargets() {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(rememberedPath(), "utf8"));
+    }
+    catch {
+        return {};
+    }
+    if (!isRecord(parsed))
+        return {};
+    return Object.fromEntries(Object.entries(parsed).flatMap(([engine, value]) => {
+        const target = targetOf(value);
+        return target ? [[engine, target]] : [];
+    }));
+}
+export function rememberEngineTargets(targets) {
+    fs.mkdirSync(path.dirname(rememberedPath()), { recursive: true });
+    fs.writeFileSync(rememberedPath(), `${JSON.stringify(targets, null, 2)}\n`);
+}
+export function forgetEngineTargets() {
+    fs.rmSync(rememberedPath(), { force: true });
+}