akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/integrations/agent/execution-preparation.js

@@ -0,0 +1,67 @@
+// 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/.
+import { cloneExecutionJsonObject } from "../../execution/json.js";
+import { withEngineFallback } from "./engine-fallback.js";
+import { planExecutionCascade, } from "./execution-cascade.js";
+import { executionEngineDefinitionsFromConfig } from "./execution-definitions.js";
+import { loadModelMap } from "./model-map.js";
+function own(value, key) {
+    return Object.hasOwn(value, key);
+}
+/** Pure common cascade composition once caller-specific sources are rendered. */
+export function planPreparedExecution(options) {
+    return planExecutionCascade({
+        command: options.command,
+        ...(own(options, "conversation") ? { conversation: options.conversation } : {}),
+        ...(own(options, "persona") ? { persona: options.persona } : {}),
+        layers: {
+            installation: {
+                id: "installation-defaults",
+                values: options.installationEngine === undefined ? {} : { engine: options.installationEngine },
+            },
+            ...(options.agentLayer ? { agent: options.agentLayer } : {}),
+            command: options.commandLayer,
+            ...(options.invocationDefaults
+                ? { invocationDefaults: { id: "invocation-defaults", values: options.invocationDefaults } }
+                : {}),
+            ...(options.current ? { current: { id: "current-invocation", values: options.current } } : {}),
+        },
+        engines: options.engines,
+        modelMap: options.modelMap,
+        invocationKind: options.invocationKind,
+        ...(options.authorizeTools ? { authorizeTools: options.authorizeTools } : {}),
+    });
+}
+/**
+ * The one planner adapter for already-rendered command/persona content.
+ * Direct, task, improve, proposal, and workflow callers contribute named
+ * layers here; none may rebuild engine/model precedence around the cascade.
+ */
+export function prepareResolvedExecution(options) {
+    const inputConfig = cloneExecutionJsonObject(options.config, "execution preparation input config");
+    const fallback = withEngineFallback(inputConfig);
+    const config = cloneExecutionJsonObject(fallback.config, "execution preparation resolved config");
+    const defaults = own(config, "defaults") ? config.defaults : undefined;
+    const installationEngine = defaults && own(defaults, "engine") ? defaults.engine : undefined;
+    const plan = planPreparedExecution({
+        command: options.command,
+        ...(own(options, "conversation") ? { conversation: options.conversation } : {}),
+        ...(own(options, "persona") ? { persona: options.persona } : {}),
+        ...(installationEngine === undefined ? {} : { installationEngine }),
+        ...(options.agentLayer ? { agentLayer: options.agentLayer } : {}),
+        commandLayer: options.commandLayer,
+        ...(options.invocationDefaults ? { invocationDefaults: options.invocationDefaults } : {}),
+        ...(options.current ? { current: options.current } : {}),
+        engines: executionEngineDefinitionsFromConfig(config),
+        modelMap: options.modelMap ?? loadModelMap().map,
+        invocationKind: options.invocationKind,
+        ...(options.authorizeTools ? { authorizeTools: options.authorizeTools } : {}),
+    });
+    return Object.freeze({
+        plan,
+        request: plan.request,
+        config,
+        ...(fallback.fallbackEngineName ? { fallbackEngineName: fallback.fallbackEngineName } : {}),
+    });
+}

package/dist/integrations/agent/index.js

@@ -1,9 +1,7 @@
 // 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/.
-export { getCommandBuilder } from "./builders.js";
 export { DEFAULT_AGENT_TIMEOUT_MS } from "./config.js";
 export { _setAgentDetectForTests, defaultWhich, detectAgentCliProfiles, pickDefaultAgentProfile } from "./detect.js";
-export { listBuiltinModelAliases, resolveModel } from "./model-aliases.js";
 export { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
 export { buildProposePrompt, buildReflectPrompt, buildSchemaRepairPrompt, extractDraftConfidence, parseAgentProposalPayload, } from "./prompts.js";

package/dist/integrations/agent/inline-execution.js

@@ -0,0 +1,74 @@
+// 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/.
+import { createInlineResolvedCommand, } from "../../execution/resolved-request.js";
+import { executionEngineDefinitionFromRunner } from "./execution-definitions.js";
+import { planPreparedExecution, prepareResolvedExecution } from "./execution-preparation.js";
+import { MODEL_MAP_VERSION } from "./model-map.js";
+const EMPTY_EXACT_MODEL_MAP = Object.freeze({
+    version: MODEL_MAP_VERSION,
+    aliases: Object.freeze(Object.create(null)),
+});
+function own(value, key) {
+    return Object.hasOwn(value, key);
+}
+/**
+ * Resolve anonymous command content through the same far-to-near cascade used
+ * by stored commands. Tasks, workflows, and internal model work adapt their
+ * already-rendered content here rather than rebuilding engine/model precedence.
+ */
+export function prepareInlineExecution(options) {
+    const command = createInlineResolvedCommand({
+        template: options.content,
+        ...(own(options, "argumentInput") ? { argumentInput: options.argumentInput } : {}),
+        content: options.content,
+    });
+    return prepareResolvedExecution({
+        command,
+        config: options.config,
+        invocationKind: options.invocationKind,
+        ...(own(options, "conversation") ? { conversation: options.conversation } : {}),
+        ...(own(options, "persona") ? { persona: options.persona } : {}),
+        commandLayer: { id: "inline-command", values: {} },
+        ...(options.invocationDefaults ? { invocationDefaults: options.invocationDefaults } : {}),
+        ...(options.current ? { current: options.current } : {}),
+        ...(options.modelMap ? { modelMap: options.modelMap } : {}),
+        ...(options.authorizeTools ? { authorizeTools: options.authorizeTools } : {}),
+    });
+}
+/**
+ * Prepare anonymous work from an already-resolved runner without reading live
+ * config or interpreting aliases. Used by resume-safe workflow/judge and by
+ * improve/proposal calls that already froze runner material.
+ */
+export function prepareInlineExecutionWithRunner(options) {
+    const command = createInlineResolvedCommand({
+        template: options.content,
+        ...(own(options, "argumentInput") ? { argumentInput: options.argumentInput } : {}),
+        content: options.content,
+    });
+    const material = executionEngineDefinitionFromRunner(options.runner, own(options, "sdkFallbackModelFromRequest")
+        ? { sdkFallbackModelFromRequest: options.sdkFallbackModelFromRequest === true }
+        : {});
+    const engines = Object.create(null);
+    Object.defineProperty(engines, material.engineName, {
+        value: material.definition,
+        enumerable: true,
+        configurable: false,
+        writable: false,
+    });
+    const plan = planPreparedExecution({
+        command,
+        ...(own(options, "conversation") ? { conversation: options.conversation } : {}),
+        ...(own(options, "persona") ? { persona: options.persona } : {}),
+        installationEngine: material.engineName,
+        commandLayer: { id: "inline-command", values: {} },
+        ...(options.invocationDefaults ? { invocationDefaults: options.invocationDefaults } : {}),
+        ...(options.current ? { current: options.current } : {}),
+        engines: Object.freeze(engines),
+        modelMap: options.modelMap ?? EMPTY_EXACT_MODEL_MAP,
+        invocationKind: options.invocationKind,
+        ...(options.authorizeTools ? { authorizeTools: options.authorizeTools } : {}),
+    });
+    return Object.freeze({ plan, request: plan.request, runner: material.runner });
+}

package/dist/integrations/agent/model-map.js

@@ -0,0 +1,515 @@
+// 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/.
+import { randomBytes } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { MAX_CONFIG_FILE_BYTES, readTextFileDescriptorWithLimit, writeFileAtomic } from "../../core/common.js";
+import { ENGINE_NAME_PATTERN_SOURCE } from "../../core/config/engine-semantics.js";
+import { ConfigError, UsageError } from "../../core/errors.js";
+import { getConfigDir } from "../../core/paths.js";
+import { cloneExecutionJsonObject } from "../../execution/json.js";
+/**
+ * Installed and operator-owned model intent aliases (#802 / WP2).
+ *
+ * The common cascade consumes this loader/expansion API for current runtime
+ * execution callers. A recognized alias expands once into exact model and
+ * inference defaults at its selecting layer; engine lowerers consume that
+ * resolved request and never reinterpret the alias. The independent API also
+ * remains usable by WP6/WP7 source and freeze adapters without hard-coding
+ * provider mappings.
+ */
+export const MODEL_MAP_VERSION = 1;
+export const MODEL_MAP_MAX_BYTES = MAX_CONFIG_FILE_BYTES;
+export const MODEL_MAP_MAX_DEPTH = 64;
+export const MODEL_MAP_MAX_NODES = 100_000;
+let standaloneInstalledModelMapText;
+const ENGINE_KEY_PATTERN = new RegExp(ENGINE_NAME_PATTERN_SOURCE);
+const ALIAS_KEY_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const RESERVED_MAP_KEYS = new Set(["__proto__", "constructor", "prototype", "tostring"]);
+function assertSafeMapKey(key, source, jsonPath) {
+    if (RESERVED_MAP_KEYS.has(key.toLowerCase())) {
+        invalid(source, jsonPath, "reserved prototype-like key is not allowed");
+    }
+}
+function invalid(source, jsonPath, detail) {
+    throw new ConfigError(`Invalid ${source} at ${jsonPath}: ${detail}`, "INVALID_CONFIG_FILE", `Fix ${source}, or remove the optional user models.json to use AKM's installed defaults.`);
+}
+function requireRecord(value, source, jsonPath) {
+    if (value === null ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        Object.getPrototypeOf(value) !== Object.prototype) {
+        invalid(source, jsonPath, "expected a JSON object");
+    }
+    return value;
+}
+function assertOnlyKeys(value, allowed, source, jsonPath) {
+    const allowedSet = new Set(allowed);
+    for (const key of Object.keys(value)) {
+        if (!allowedSet.has(key))
+            invalid(source, `${jsonPath}.${key}`, "unknown field");
+    }
+}
+function requireNonemptyString(value, source, jsonPath) {
+    if (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
+        invalid(source, jsonPath, "expected a nonempty string without surrounding whitespace");
+    }
+    return value;
+}
+function freezeRecord(entries) {
+    const record = Object.create(null);
+    for (const [key, value] of entries)
+        record[key] = value;
+    return Object.freeze(record);
+}
+function ownValue(record, key) {
+    return record !== undefined && Object.hasOwn(record, key) ? record[key] : undefined;
+}
+function parseProfileLayer(value, source, jsonPath) {
+    if (typeof value === "string")
+        return requireNonemptyString(value, source, jsonPath);
+    const record = requireRecord(value, source, jsonPath);
+    assertOnlyKeys(record, ["model", "inference"], source, jsonPath);
+    if (!Object.hasOwn(record, "model") && !Object.hasOwn(record, "inference")) {
+        invalid(source, jsonPath, "structured profile must contain model and/or inference");
+    }
+    const out = {};
+    if (Object.hasOwn(record, "model"))
+        out.model = requireNonemptyString(record.model, source, `${jsonPath}.model`);
+    if (Object.hasOwn(record, "inference")) {
+        if (record.inference === null)
+            out.inference = null;
+        else {
+            try {
+                out.inference = cloneExecutionJsonObject(record.inference, `${source} ${jsonPath}.inference`);
+            }
+            catch (error) {
+                invalid(source, `${jsonPath}.inference`, error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    return Object.freeze(out);
+}
+/**
+ * Bound nesting before JSON.parse or any recursive durable-JSON clone runs.
+ * Brackets inside strings are ignored, including escaped quote sequences.
+ */
+function assertJsonDepthBudget(text, source) {
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (const character of text) {
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (character === "\\")
+                escaped = true;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (character === '"') {
+            inString = true;
+            continue;
+        }
+        if (character === "{" || character === "[") {
+            depth += 1;
+            if (depth > MODEL_MAP_MAX_DEPTH) {
+                invalid(source, "$", `JSON nesting exceeds the ${MODEL_MAP_MAX_DEPTH}-level limit`);
+            }
+        }
+        else if (character === "}" || character === "]") {
+            depth -= 1;
+        }
+    }
+}
+/** Iterative node budget, deliberately completed before recursive inference cloning. */
+function assertJsonNodeBudget(value, source) {
+    const pending = [value];
+    let count = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        count += 1;
+        if (count > MODEL_MAP_MAX_NODES) {
+            invalid(source, "$", `JSON value exceeds the ${MODEL_MAP_MAX_NODES}-node limit`);
+        }
+        if (current !== null && typeof current === "object") {
+            const children = Array.isArray(current) ? current : Object.values(current);
+            for (const child of children)
+                pending.push(child);
+        }
+    }
+}
+/** Parse one installed or user layer. Partial structured profiles are valid at this stage. */
+export function parseModelMapLayer(text, source) {
+    if (Buffer.byteLength(text, "utf8") > MODEL_MAP_MAX_BYTES) {
+        invalid(source, "$", `document exceeds the ${MODEL_MAP_MAX_BYTES}-byte limit`);
+    }
+    assertJsonDepthBudget(text, source);
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        invalid(source, "$", "invalid JSON syntax");
+    }
+    assertJsonNodeBudget(parsed, source);
+    const root = requireRecord(parsed, source, "$");
+    assertOnlyKeys(root, ["version", "aliases"], source, "$");
+    if (root.version !== MODEL_MAP_VERSION) {
+        invalid(source, "$.version", `expected version ${MODEL_MAP_VERSION}`);
+    }
+    if (!Object.hasOwn(root, "aliases"))
+        invalid(source, "$.aliases", "required field is missing");
+    const rawAliases = requireRecord(root.aliases, source, "$.aliases");
+    const aliases = [];
+    const aliasesSeen = new Map();
+    for (const [rawAlias, rawEngines] of Object.entries(rawAliases)) {
+        const alias = rawAlias.toLowerCase();
+        assertSafeMapKey(alias, source, `$.aliases.${rawAlias}`);
+        if (!ALIAS_KEY_PATTERN.test(alias))
+            invalid(source, `$.aliases.${rawAlias}`, "alias must be lowercase kebab-case");
+        const previous = aliasesSeen.get(alias);
+        if (previous !== undefined) {
+            invalid(source, `$.aliases.${rawAlias}`, `alias collides case-insensitively with ${previous}`);
+        }
+        aliasesSeen.set(alias, rawAlias);
+        const engineRecord = requireRecord(rawEngines, source, `$.aliases.${rawAlias}`);
+        if (Object.keys(engineRecord).length === 0) {
+            invalid(source, `$.aliases.${rawAlias}`, "alias must contain at least one engine mapping");
+        }
+        const engines = [];
+        const enginesSeen = new Map();
+        for (const [rawEngine, rawProfile] of Object.entries(engineRecord)) {
+            const engine = rawEngine.toLowerCase();
+            assertSafeMapKey(engine, source, `$.aliases.${rawAlias}.${rawEngine}`);
+            if (!ENGINE_KEY_PATTERN.test(engine)) {
+                invalid(source, `$.aliases.${rawAlias}.${rawEngine}`, "engine key must be lowercase kebab-case");
+            }
+            const previousEngine = enginesSeen.get(engine);
+            if (previousEngine !== undefined) {
+                invalid(source, `$.aliases.${rawAlias}.${rawEngine}`, `engine key collides case-insensitively with ${previousEngine}`);
+            }
+            enginesSeen.set(engine, rawEngine);
+            engines.push([engine, parseProfileLayer(rawProfile, source, `$.aliases.${rawAlias}.${rawEngine}`)]);
+        }
+        aliases.push([alias, freezeRecord(engines)]);
+    }
+    return Object.freeze({ version: MODEL_MAP_VERSION, aliases: freezeRecord(aliases) });
+}
+function isJsonObject(value) {
+    return value !== null && value !== undefined && typeof value === "object" && !Array.isArray(value);
+}
+function mergeJsonValue(base, overlay) {
+    if (!isJsonObject(base) || !isJsonObject(overlay))
+        return overlay;
+    const entries = new Map(Object.entries(base));
+    for (const [key, value] of Object.entries(overlay))
+        entries.set(key, mergeJsonValue(entries.get(key), value));
+    return Object.freeze(Object.fromEntries(entries));
+}
+function normalizeLayerEntry(entry) {
+    return typeof entry === "string" ? Object.freeze({ model: entry }) : entry;
+}
+function mergeProfiles(base, overlay) {
+    const next = normalizeLayerEntry(overlay);
+    const out = {};
+    if (base?.model !== undefined)
+        out.model = base.model;
+    if (base && Object.hasOwn(base, "inference"))
+        out.inference = base.inference;
+    if (next.model !== undefined)
+        out.model = next.model;
+    if (Object.hasOwn(next, "inference")) {
+        out.inference =
+            next.inference !== null && next.inference !== undefined && isJsonObject(base?.inference)
+                ? mergeJsonValue(base.inference, next.inference)
+                : next.inference;
+    }
+    return Object.freeze(out);
+}
+/** Overlay user fields over installed fields, then enforce usable merged profiles. */
+export function mergeModelMapLayers(installed, user) {
+    const aliases = new Map();
+    const apply = (layer) => {
+        for (const [alias, engines] of Object.entries(layer.aliases)) {
+            const mergedEngines = aliases.get(alias) ?? new Map();
+            for (const [engine, profile] of Object.entries(engines)) {
+                mergedEngines.set(engine, mergeProfiles(mergedEngines.get(engine), profile));
+            }
+            aliases.set(alias, mergedEngines);
+        }
+    };
+    apply(installed);
+    if (user)
+        apply(user);
+    const resolvedAliases = [];
+    for (const [alias, engines] of aliases) {
+        const resolvedEngines = [];
+        for (const [engine, profile] of engines) {
+            if (profile.model === undefined) {
+                invalid("merged models.json", `$.aliases.${alias}.${engine}.model`, "a usable model is required after overlay");
+            }
+            resolvedEngines.push([engine, Object.freeze({ ...profile, model: profile.model })]);
+        }
+        resolvedAliases.push([alias, freezeRecord(resolvedEngines)]);
+    }
+    return Object.freeze({ version: MODEL_MAP_VERSION, aliases: freezeRecord(resolvedAliases) });
+}
+function selectionFromProfile(input, profile) {
+    if (!profile.model)
+        throw new ConfigError(`Model alias ${JSON.stringify(input)} does not resolve to a usable model.`);
+    return Object.freeze({
+        input,
+        interpretation: "alias",
+        model: profile.model,
+        ...(Object.hasOwn(profile, "inference") ? { inference: profile.inference } : {}),
+    });
+}
+/** Resolve one alias through the merged installed/user registry. */
+export function resolveModelMapAlias(input, engine, map) {
+    const alias = input.toLowerCase();
+    const selectedEngine = engine.toLowerCase();
+    const tier = ownValue(map.aliases, alias);
+    const profile = ownValue(tier, selectedEngine);
+    if (profile !== undefined)
+        return selectionFromProfile(input, profile);
+    if (tier !== undefined) {
+        throw new ConfigError(`Known alias ${JSON.stringify(input)} has no model mapping for selected engine ${JSON.stringify(engine)}.`, "INVALID_CONFIG_FILE", `Add $.aliases.${alias}.${engine} to models.json.`);
+    }
+    return Object.freeze({ input, interpretation: "exact", model: input });
+}
+export function userModelMapPath(env = process.env) {
+    return path.join(getConfigDir(env), "models.json");
+}
+function modelMapFileError(label, filePath, action) {
+    return new ConfigError(`${label} could not be ${action}: ${filePath}.`, "INVALID_CONFIG_FILE", `Ensure ${filePath} is a readable regular file owned by the expected user.`);
+}
+/**
+ * Read through a nonblocking, no-follow descriptor and enforce the config-size
+ * ceiling before parsing. `optional` recognizes only a true lstat ENOENT as
+ * absence; dangling links and every non-regular type are configuration errors.
+ */
+function readModelMapFile(filePath, label, optional) {
+    let linkStat;
+    try {
+        linkStat = fs.lstatSync(filePath);
+    }
+    catch (error) {
+        if (optional && error?.code === "ENOENT")
+            return undefined;
+        throw modelMapFileError(label, filePath, optional ? "inspected" : "found");
+    }
+    if (!linkStat.isFile()) {
+        throw new ConfigError(`Unable to read ${label.toLowerCase()} because it is not a readable regular file: ${filePath}.`, "INVALID_CONFIG_FILE", "Move the symlink or non-regular target aside, or replace it with a readable regular models.json file.");
+    }
+    const noFollow = process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    const nonblock = process.platform !== "win32" && typeof fs.constants.O_NONBLOCK === "number" ? fs.constants.O_NONBLOCK : 0;
+    let fd;
+    try {
+        fd = fs.openSync(filePath, fs.constants.O_RDONLY | noFollow | nonblock);
+        const openedStat = fs.fstatSync(fd);
+        if (!sameFileIdentity(linkStat, openedStat)) {
+            throw new ConfigError(`${label} changed while it was being opened: ${filePath}.`, "INVALID_CONFIG_FILE", "Retry after ensuring no other process is replacing models.json.");
+        }
+        const text = readTextFileDescriptorWithLimit(fd, MODEL_MAP_MAX_BYTES, label, filePath);
+        fs.closeSync(fd);
+        fd = undefined;
+        return text;
+    }
+    catch (error) {
+        if (error instanceof ConfigError)
+            throw error;
+        throw modelMapFileError(label, filePath, "read");
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // The actionable read error above remains authoritative.
+            }
+        }
+    }
+}
+/** Resolve the one authoritative external-asset location for this runtime. */
+export function installedModelMapPaths(moduleUrl = import.meta.url) {
+    const modulePath = fileURLToPath(moduleUrl);
+    const moduleDirectory = path.dirname(modulePath);
+    const unbundledModule = path.basename(moduleDirectory) === "agent" && path.basename(path.dirname(moduleDirectory)) === "integrations";
+    const assetPath = path.resolve(moduleDirectory, unbundledModule ? "../../assets/models.json" : "assets/models.json");
+    return Object.freeze([assetPath]);
+}
+/**
+ * Standalone bootstrap only. `scripts/akm-standalone.ts` derives these bytes
+ * from the authoritative JSON import that Bun embeds into the executable.
+ */
+export function registerStandaloneModelMapFallback(text) {
+    standaloneInstalledModelMapText = text;
+}
+/** Load installed bytes lazily so health can report a missing/bad package asset. */
+export function readInstalledModelMapText(options = {}) {
+    if (options.installedText !== undefined)
+        return options.installedText;
+    // Registration occurs only in the compiled standalone bootstrap. Once set,
+    // the embedded authority must win over any mutable file beside the binary.
+    if (standaloneInstalledModelMapText !== undefined)
+        return standaloneInstalledModelMapText;
+    const candidates = installedModelMapPaths();
+    for (const candidate of candidates) {
+        const external = readModelMapFile(candidate, "Installed models.json", true);
+        if (external !== undefined)
+            return external;
+    }
+    throw new ConfigError(`Installed models.json is missing from this AKM installation (checked: ${candidates.join(", ")}).`, "INVALID_CONFIG_FILE", "Reinstall AKM so its dist/assets/models.json package asset is restored.");
+}
+/** Load the installed authority plus the optional operator overlay. */
+export function loadModelMap(options = {}) {
+    const installed = parseModelMapLayer(readInstalledModelMapText(options), "installed models.json");
+    const userPath = userModelMapPath(options.env);
+    const userText = readModelMapFile(userPath, "User models.json", true);
+    let user;
+    if (userText !== undefined)
+        user = parseModelMapLayer(userText, `user models.json (${userPath})`);
+    return Object.freeze({ map: mergeModelMapLayers(installed, user), userPath, userStatus: user ? "loaded" : "absent" });
+}
+function targetExistsError(target, detail) {
+    return new UsageError(`${detail}: ${target}`, "RESOURCE_ALREADY_EXISTS", "Move the existing target aside, then retry. Use --overwrite only for a stable regular file you intend to replace.");
+}
+function copyIoError(target, action, hint) {
+    return new ConfigError(`Unable to ${action} user models.json at ${target}.`, "INVALID_CONFIG_FILE", hint ?? "Check the configuration directory ownership and permissions, then retry.");
+}
+function inspectCopyTarget(target) {
+    try {
+        return fs.lstatSync(target);
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return undefined;
+        throw copyIoError(target, "inspect");
+    }
+}
+function sameFileIdentity(left, right) {
+    if (!left.isFile() || !right.isFile())
+        return false;
+    if (left.dev !== 0 || left.ino !== 0 || right.dev !== 0 || right.ino !== 0) {
+        return left.dev === right.dev && left.ino === right.ino;
+    }
+    return left.mode === right.mode && left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+function syncCopyDirectory(directory) {
+    if (process.platform === "win32")
+        return;
+    let fd;
+    try {
+        fd = fs.openSync(directory, fs.constants.O_RDONLY);
+        fs.fsyncSync(fd);
+        fs.closeSync(fd);
+        fd = undefined;
+    }
+    catch (error) {
+        const code = error?.code;
+        if (code !== "EINVAL" && code !== "ENOTSUP")
+            throw error;
+    }
+    finally {
+        if (fd !== undefined) {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // A preceding sync/open failure is more useful than a cleanup failure.
+            }
+        }
+    }
+}
+function stageDefaultModelMap(target, text) {
+    const stage = `${target}.copy.${process.pid}.${randomBytes(8).toString("hex")}`;
+    try {
+        writeFileAtomic(stage, text, 0o600);
+        return stage;
+    }
+    catch {
+        throw copyIoError(target, "write a staged copy of");
+    }
+}
+/** Explicitly copy validated installed bytes into the normal config directory. */
+export function copyDefaultModelMap(options = {}) {
+    const text = readInstalledModelMapText(options);
+    mergeModelMapLayers(parseModelMapLayer(text, "installed models.json"));
+    const target = userModelMapPath(options.env);
+    try {
+        fs.mkdirSync(path.dirname(target), { recursive: true, mode: 0o700 });
+    }
+    catch {
+        throw copyIoError(target, "create the configuration directory for");
+    }
+    const existing = inspectCopyTarget(target);
+    if (existing && !existing.isFile()) {
+        throw targetExistsError(target, "Refusing to replace a non-regular models.json target");
+    }
+    if (existing && options.overwrite !== true) {
+        throw targetExistsError(target, "User models.json already exists");
+    }
+    const stage = stageDefaultModelMap(target, text);
+    let stagePresent = true;
+    try {
+        if (existing === undefined) {
+            try {
+                // Hard-link publication is an atomic no-replace operation: EEXIST
+                // means a racing creator won, and their bytes remain untouched.
+                fs.linkSync(stage, target);
+            }
+            catch (error) {
+                if (error?.code === "EEXIST") {
+                    throw targetExistsError(target, "User models.json was created while defaults were being prepared");
+                }
+                throw copyIoError(target, "publish");
+            }
+            try {
+                fs.unlinkSync(stage);
+                stagePresent = false;
+            }
+            catch {
+                // The target was already published atomically. Cleanup is best-effort
+                // from this point forward; `finally` retries without turning a
+                // successful copy into a false failure.
+            }
+        }
+        else {
+            const current = inspectCopyTarget(target);
+            if (!current || !sameFileIdentity(existing, current)) {
+                throw targetExistsError(target, "User models.json changed while defaults were being prepared");
+            }
+            try {
+                // rename replaces the directory entry itself; it never follows a
+                // symlink inserted after the final identity check.
+                fs.renameSync(stage, target);
+                stagePresent = false;
+            }
+            catch {
+                throw copyIoError(target, "replace");
+            }
+        }
+    }
+    finally {
+        if (stagePresent) {
+            try {
+                fs.unlinkSync(stage);
+            }
+            catch {
+                // Best-effort cleanup; the target was never published from this path.
+            }
+        }
+    }
+    try {
+        syncCopyDirectory(path.dirname(target));
+    }
+    catch {
+        throw copyIoError(target, "durably publish", `The target may already exist at ${target}; inspect it before retrying because directory durability could not be confirmed.`);
+    }
+    return { path: target, copied: true, overwritten: existing !== undefined };
+}