akm-cli 0.9.14 → 0.9.15-beta.2

package/dist/indexer/search/db-search.js

@@ -25,7 +25,7 @@ import { allowsFragmentRef, defaultRendererRegistry } from "../../core/type-pres
 import { normalizeEmbeddingEndpoint } from "../../llm/embedders/remote.js";
 import { assertIndexPathReadable, closeDatabase, openExistingDatabase, } from "../../storage/repositories/index-connection.js";
 import { getAllEntries, getBaseBeliefStatesForDerivedTwins, getEntryById, getEntryCount, getPositiveFeedbackCountsByIds, } from "../../storage/repositories/index-entries-repository.js";
-import { searchFts } from "../../storage/repositories/index-fts-repository.js";
+import { getIndexedMarkdownFragment, getIndexedMarkdownFragments, searchFts, } from "../../storage/repositories/index-fts-repository.js";
 import { getMeta } from "../../storage/repositories/index-meta-repository.js";
 import { getEmbeddingCount, searchVec } from "../../storage/repositories/index-vec-repository.js";
 import { getCurrentWorkflowScopeKey } from "../../workflows/authoring/scope-key.js";
@@ -451,6 +451,14 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
     });
     const rankMs = Date.now() - tRank0;
     const selected = beliefFiltered.slice(0, limit);
+    const fragmentSelections = selected.flatMap((ranked) => ranked.fragmentId && allowsFragmentRef(ranked.entry.type) && hasIndexedProvenance(ranked)
+        ? [{ entryId: ranked.id, itemRef: ranked.itemRef, fragmentId: ranked.fragmentId }]
+        : []);
+    const selectedFragments = getIndexedMarkdownFragments(db, fragmentSelections);
+    const selectedFragmentByEntryId = new Map();
+    fragmentSelections.forEach((selection, index) => {
+        selectedFragmentByEntryId.set(selection.entryId, selectedFragments[index]);
+    });
     const hits = await Promise.all(selected.map((ranked) => {
         const { entry, filePath, score, rankingMode, utilityBoosted } = ranked;
         // CLAUDE.md locks SearchHit.score in [0,1]. The boost loop deliberately
@@ -467,6 +475,7 @@ async function searchDatabase(db, query, searchType, limit, stashDir, allSourceD
             rankingMode,
             lexicalMatch: ranked.lexicalMatch,
             fragmentId: ranked.fragmentId,
+            indexedFragment: ranked.fragmentId ? (selectedFragmentByEntryId.get(ranked.id) ?? null) : undefined,
             defaultStashDir: stashDir,
             allSourceDirs,
             sources,
@@ -788,7 +797,19 @@ export async function buildDbHit(input) {
     // The central type-presentation contract opts those types out explicitly.
     const ref = input.fragmentId && allowsFragmentRef(input.entry.type) ? `${parentRef}#${input.fragmentId}` : parentRef;
     const editable = isEditable(absolutePath, input.config, input.sources);
-    const estimatedTokens = typeof input.entry.fileSize === "number" ? Math.round(input.entry.fileSize / 4) : undefined;
+    const indexedFragment = input.indexedFragment === undefined
+        ? input.fragmentId && input.db
+            ? getIndexedMarkdownFragment(input.db, input.itemRef, input.fragmentId)
+            : undefined
+        : (input.indexedFragment ?? undefined);
+    const selectedRef = input.fragmentId && ref !== parentRef ? `${parentRef}#${input.fragmentId}` : undefined;
+    const parentEstimatedTokens = typeof input.entry.fileSize === "number"
+        ? Math.round(input.entry.fileSize / 4)
+        : indexedFragment
+            ? Math.round(indexedFragment.parentChars / 4)
+            : undefined;
+    const fragmentEstimatedTokens = indexedFragment ? Math.round(indexedFragment.fragmentChars / 4) : undefined;
+    const estimatedTokens = selectedRef === ref && fragmentEstimatedTokens !== undefined ? fragmentEstimatedTokens : parentEstimatedTokens;
     const hit = {
         type: input.entry.type,
         name: input.entry.name,
@@ -804,6 +825,32 @@ export async function buildDbHit(input) {
         score,
         whyMatched,
         ...(estimatedTokens !== undefined ? { estimatedTokens } : {}),
+        ...(selectedRef
+            ? {
+                selectedRef,
+                parentRef,
+                ...(indexedFragment
+                    ? {
+                        fragmentOrdinal: indexedFragment.ordinal + 1,
+                        fragmentCount: indexedFragment.count,
+                        startLine: indexedFragment.startLine,
+                        endLine: indexedFragment.endLine,
+                        ...(indexedFragment.previousFragmentId
+                            ? { previousRef: `${parentRef}#${indexedFragment.previousFragmentId}` }
+                            : {}),
+                        ...(indexedFragment.nextFragmentId
+                            ? { nextRef: `${parentRef}#${indexedFragment.nextFragmentId}` }
+                            : {}),
+                        fragmentChars: indexedFragment.fragmentChars,
+                        fragmentEstimatedTokens,
+                        parentChars: indexedFragment.parentChars,
+                        ...(parentEstimatedTokens !== undefined ? { parentEstimatedTokens } : {}),
+                    }
+                    : parentEstimatedTokens !== undefined
+                        ? { parentEstimatedTokens }
+                        : {}),
+            }
+            : {}),
         // Surface optional quality (v1 spec §4.2). Omitted when entry has
         // no `quality` field so payloads stay compact for the common case.
         ...(input.entry.quality ? { quality: input.entry.quality } : {}),

package/dist/indexer/search/search-source.js

@@ -238,6 +238,7 @@ export async function ensureSourceCaches(config, options) {
     const cfg = config ?? loadConfig();
     const force = options?.force === true;
     const materialize = options?.materialize !== false;
+    const onProgress = options?.onProgress ?? (() => { });
     // Polymorphic refresh: walk every enabled source through its registered
     // provider and call `sync()`. Every cache-backed kind (git, website, npm)
     // refreshes the same way — a bad source warns and is skipped without
@@ -249,6 +250,12 @@ export async function ensureSourceCaches(config, options) {
     // content ENDS UP; the lock's `localRoot` merely records the result. So this
     // path correctly uses the provider, not the shared `lockContentRootFor`
     // resolver that reads/writes use to agree on where content already IS.
+    //
+    // Two passes: first resolve which sources will actually sync (constructing
+    // each provider once, exactly as before), so the progress count ("i/n")
+    // reflects real syncs rather than every configured entry including managed/
+    // unsyncable ones; then sync them in order, reporting progress per source.
+    const toSync = [];
     for (const entry of getSources(cfg)) {
         if (entry.enabled === false)
             continue;
@@ -282,12 +289,27 @@ export async function ensureSourceCaches(config, options) {
             warnIfSourceUnavailableForRead(entry, provider.name);
             continue;
         }
+        toSync.push(provider);
+    }
+    for (const [i, provider] of toSync.entries()) {
+        onProgress(`Hydrating source ${i + 1}/${toSync.length}: ${provider.name}`);
+        let heartbeat;
         try {
-            await provider.sync({ force, secrets: options?.secrets, ensureWebsiteMirror });
+            heartbeat = setInterval(() => {
+                onProgress(`Still hydrating source ${i + 1}/${toSync.length}: ${provider.name}...`);
+            }, 15000);
+            // `toSync` only ever holds providers whose `.sync` passed the check
+            // above; the optional-chain here is just to satisfy the type (the
+            // narrowing does not survive the array round-trip).
+            await provider.sync?.({ force, secrets: options?.secrets, ensureWebsiteMirror });
         }
         catch (err) {
             warn(`Warning: failed to refresh ${provider.kind} source "${provider.name}": ${err instanceof Error ? err.message : String(err)}`);
         }
+        finally {
+            if (heartbeat)
+                clearInterval(heartbeat);
+        }
     }
 }
 /**

package/dist/integrations/agent/engine-resolution.js

@@ -4,11 +4,14 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { resolveSecret } from "../../core/config/config.js";
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { SECRET_STORE_REFERENCE_PATTERN } from "../../core/config/schema/primitives.js";
 import { ConfigError } from "../../core/errors.js";
 import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
 import { collectSensitiveValues } from "../../core/redaction.js";
 import { warn } from "../../core/warn.js";
+import { resolveSecretFromStore } from "../../sources/snapshot-fetchers/secret-seam.js";
 import { getHarness } from "../harnesses/index.js";
 import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "./config.js";
 import { getBuiltinAgentProfile } from "./profiles.js";
@@ -70,6 +73,21 @@ export function lookupApiKeyFileValue(filePath) {
         return undefined;
     }
 }
+/**
+ * Best-effort, non-throwing read of a secret-store-backed credential's
+ * current value (#953), for redaction inventories and health probes that
+ * must never fail just because a value collector ran ahead of the real
+ * dispatch — an unresolvable reference is reported by
+ * {@link resolveLlmCredentialValue} at the actual call.
+ */
+export function lookupApiKeySecretRefValue(ref) {
+    try {
+        return resolveSecret(ref, resolveSecretFromStore);
+    }
+    catch {
+        return undefined;
+    }
+}
 function selectedEngineName(config, layers, llmOnly) {
     for (let index = layers.length - 1; index >= 0; index--) {
         const layer = layers[index];
@@ -94,9 +112,14 @@ function resolveCredential(name, engine, config) {
     const apiKey = ownValue(engine, "apiKey");
     if (apiKey !== undefined) {
         const explicit = envName(apiKey);
-        if (!explicit)
-            throw new ConfigError(`Engine "${name}" has an invalid symbolic apiKey reference.`, "INVALID_CONFIG_FILE");
-        return { names: [explicit], required: true };
+        if (explicit)
+            return { names: [explicit], required: true };
+        // #953: a secret-store reference has no env descriptor — resolved
+        // separately onto `ResolvedLlmUse.apiKeySecretRef` — mirroring how
+        // apiKeyFile above is its own credential source.
+        if (SECRET_STORE_REFERENCE_PATTERN.test(apiKey))
+            return undefined;
+        throw new ConfigError(`Engine "${name}" has an invalid symbolic apiKey reference.`, "INVALID_CONFIG_FILE");
     }
     // #905: an explicit apiKeyFile is its own credential source — resolved
     // separately onto `ResolvedLlmUse.apiKeyFile` — so it does not also fall
@@ -142,11 +165,66 @@ export function resolveCredentialFromEnv(credential, envSource = process.env) {
  * so a whole operation observes one stable credential value instead of
  * re-reading the file on every dispatch within it.
  */
-export function resolveLlmCredentialValue(engine, credential, apiKeyFile, envSource = process.env) {
+export function resolveLlmCredentialValue(engine, credential, apiKeyFile, apiKeySecretRef, envSource = process.env) {
     const envValue = resolveCredentialFromEnv(credential, envSource);
     if (envValue !== undefined)
         return envValue;
-    return apiKeyFile !== undefined ? readApiKeyFile(engine, apiKeyFile) : undefined;
+    if (apiKeyFile !== undefined)
+        return readApiKeyFile(engine, apiKeyFile);
+    // #953: a secret-store reference is the last fallback tier, reusing the
+    // same resolveSecret() helper llm/client.ts and embedders/remote.ts call
+    // directly — throws SECRET_REFERENCE_UNRESOLVED naming only the reference.
+    return apiKeySecretRef !== undefined ? resolveSecret(apiKeySecretRef, resolveSecretFromStore) : undefined;
+}
+/**
+ * Non-throwing credential-presence check for `akm health`, the
+ * improve-strategy probe (#953), and improve's own plan builder (#957): an env
+ * value is present, or a file-backed credential is readable and non-empty, or
+ * a secret-store reference resolves. Never reads env/disk/store speculatively
+ * beyond what's needed to answer "is something here", and never throws on a
+ * broken/missing source — that is reported by {@link resolveLlmCredentialValue}
+ * at the real dispatch.
+ *
+ * On failure, `reference` and `reason` name WHICH env var / file / secret
+ * reference is missing (never its value) — the operator's own shell often
+ * passes the same check a scheduler's stripped-down environment fails, so the
+ * caller needs to say which reference is the problem. Callers that must never
+ * name the reference (`akm health`'s evidence/message) use only `.available`.
+ */
+export function describeLlmCredentialAvailability(resolved, env = process.env) {
+    if (resolved.credential?.required) {
+        if (resolved.credential.names.some((name) => Boolean(env[name]?.trim())))
+            return { available: true };
+        const reference = `$${resolved.credential.names[0]}`;
+        return { available: false, reference, reason: `${reference} is not set in this environment` };
+    }
+    if (resolved.apiKeyFile !== undefined) {
+        if (lookupApiKeyFileValue(resolved.apiKeyFile) !== undefined)
+            return { available: true };
+        return {
+            available: false,
+            reference: resolved.apiKeyFile,
+            reason: `apiKeyFile ${resolved.apiKeyFile} is missing or empty`,
+        };
+    }
+    if (resolved.apiKeySecretRef !== undefined) {
+        if (lookupApiKeySecretRefValue(resolved.apiKeySecretRef) !== undefined)
+            return { available: true };
+        return {
+            available: false,
+            reference: resolved.apiKeySecretRef,
+            reason: `${resolved.apiKeySecretRef} did not resolve from the secret store`,
+        };
+    }
+    return { available: true };
+}
+/**
+ * Thin boolean wrapper over {@link describeLlmCredentialAvailability} for
+ * callers (`akm health`'s engine-reachability probes) that only need a
+ * yes/no answer and never surface the reference.
+ */
+export function isLlmCredentialAvailable(resolved, env = process.env) {
+    return describeLlmCredentialAvailability(resolved, env).available;
 }
 /** Collect materialized engine credentials for output and persistence redaction. */
 export function collectEngineCredentialValues(config, envSource = process.env) {
@@ -168,6 +246,13 @@ export function collectEngineCredentialValues(config, envSource = process.env) {
             if (value)
                 values.add(value);
         }
+        // #953: secret-store-backed credential — best-effort for the same reason.
+        const apiKey = ownValue(engine, "apiKey");
+        if (apiKey !== undefined && SECRET_STORE_REFERENCE_PATTERN.test(apiKey)) {
+            const value = lookupApiKeySecretRefValue(apiKey);
+            if (value)
+                values.add(value);
+        }
     }
     return collectSensitiveValues(values);
 }
@@ -235,11 +320,14 @@ export function resolveLlmEngineUse(config, layers, options = {}) {
             delete connection[key];
     }
     const apiKeyFile = ownValue(engine, "apiKeyFile");
+    const apiKeyRaw = ownValue(engine, "apiKey");
+    const apiKeySecretRef = apiKeyRaw !== undefined && SECRET_STORE_REFERENCE_PATTERN.test(apiKeyRaw) ? apiKeyRaw : undefined;
     return {
         engine: name,
         connection: sterileRecord(connection),
         credential: resolveCredential(name, engine, config),
         ...(apiKeyFile !== undefined ? { apiKeyFile: expandHomePath(apiKeyFile) } : {}),
+        ...(apiKeySecretRef !== undefined ? { apiKeySecretRef } : {}),
         timeoutMs: effectiveTimeout(engine, layers, DEFAULT_LLM_TIMEOUT_MS),
     };
 }
@@ -270,7 +358,7 @@ export function materializeLlmConnectionWithCredential(resolved, credentialValue
  * engine has no env descriptor.
  */
 export function materializeLlmConnection(resolved, envSource = process.env) {
-    return materializeLlmConnectionWithCredential(resolved, resolveLlmCredentialValue(resolved.engine, resolved.credential, resolved.apiKeyFile, envSource));
+    return materializeLlmConnectionWithCredential(resolved, resolveLlmCredentialValue(resolved.engine, resolved.credential, resolved.apiKeyFile, resolved.apiKeySecretRef, envSource));
 }
 function lowerAgentEngine(name, engine, config) {
     const harness = getHarness(engine.platform);
@@ -319,6 +407,7 @@ function lowerAgentEngine(name, engine, config) {
                 fallbackConnection: fallback.connection,
                 ...(fallback.credential ? { fallbackCredential: fallback.credential } : {}),
                 ...(fallback.apiKeyFile ? { fallbackApiKeyFile: fallback.apiKeyFile } : {}),
+                ...(fallback.apiKeySecretRef ? { fallbackApiKeySecretRef: fallback.apiKeySecretRef } : {}),
                 fallbackTimeoutMs: fallback.timeoutMs,
             }
             : {}),
@@ -340,6 +429,7 @@ export function resolveEngine(name, config) {
             connection: resolved.connection,
             ...(resolved.credential ? { credential: resolved.credential } : {}),
             ...(resolved.apiKeyFile ? { apiKeyFile: resolved.apiKeyFile } : {}),
+            ...(resolved.apiKeySecretRef ? { apiKeySecretRef: resolved.apiKeySecretRef } : {}),
             timeoutMs: resolved.timeoutMs,
         };
     }

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

@@ -3,6 +3,7 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { cloneExecutionJsonObject } from "../../execution/json.js";
 import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "./config.js";
+import { engineModelAndInference } from "./model-map.js";
 import { OPENCODE_SDK_SERVER_BIN } from "./profiles.js";
 /**
  * Canonical engine-setting marker: an SDK without its own model selected the
@@ -22,25 +23,15 @@ function withoutUndefined(value) {
 }
 function engineDefaults(engine) {
     const defaults = {};
-    if (own(engine, "model"))
-        defaults.model = engine.model;
+    const { model, inference } = engineModelAndInference(engine);
+    if (model !== undefined)
+        defaults.model = model;
     if (own(engine, "timeoutMs"))
         defaults.timeout = engine.timeoutMs;
     if (engine.kind === "agent" && own(engine, "workspace"))
         defaults.workspace = engine.workspace;
-    if (engine.kind === "llm") {
-        const inference = withoutUndefined({
-            temperature: ownValue(engine, "temperature"),
-            maxTokens: ownValue(engine, "maxTokens"),
-            supportsJsonSchema: ownValue(engine, "supportsJsonSchema"),
-            extraParams: ownValue(engine, "extraParams"),
-            contextLength: ownValue(engine, "contextLength"),
-            enableThinking: ownValue(engine, "enableThinking"),
-            reasoningEffort: ownValue(engine, "reasoningEffort"),
-        });
-        if (Object.keys(inference).length > 0)
-            defaults.inference = inference;
-    }
+    if (inference !== undefined)
+        defaults.inference = inference;
     return Object.freeze(defaults);
 }
 function configuredSdkFallback(engine, config) {

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

@@ -210,13 +210,16 @@ function snapshotRunnerSpec(input, options = {}) {
     if (own(cloned, "timeoutMs"))
         validateTimeout(cloned.timeoutMs, "execution runner material.timeoutMs");
     if (kind === "llm") {
-        assertKeys(cloned, ["kind", "engine", "connection", "credential", "apiKeyFile", "timeoutMs"], "execution runner material");
+        assertKeys(cloned, ["kind", "engine", "connection", "credential", "apiKeyFile", "apiKeySecretRef", "timeoutMs"], "execution runner material");
         validateConnection(cloned.connection, "execution runner material.connection", !options.allowMissingLlmModel);
         if (own(cloned, "credential"))
             validateCredential(cloned.credential, "execution runner material.credential");
         // #905: a path, not the secret itself — as safe to freeze as `credential`'s
         // env-var name.
         validateOptionalString(cloned, "apiKeyFile", "execution runner material");
+        // #953: a `secret://<name>` reference, not the secret itself — same
+        // freeze-safety rationale as apiKeyFile above.
+        validateOptionalString(cloned, "apiKeySecretRef", "execution runner material");
     }
     else if (kind === "agent") {
         assertKeys(cloned, ["kind", "engine", "profile", "timeoutMs"], "execution runner material");
@@ -230,6 +233,7 @@ function snapshotRunnerSpec(input, options = {}) {
             "fallbackConnection",
             "fallbackCredential",
             "fallbackApiKeyFile",
+            "fallbackApiKeySecretRef",
             "fallbackTimeoutMs",
             "timeoutMs",
         ], "execution runner material");
@@ -241,6 +245,7 @@ function snapshotRunnerSpec(input, options = {}) {
             validateCredential(cloned.fallbackCredential, "execution runner material.fallbackCredential");
         }
         validateOptionalString(cloned, "fallbackApiKeyFile", "execution runner material");
+        validateOptionalString(cloned, "fallbackApiKeySecretRef", "execution runner material");
         if (own(cloned, "fallbackTimeoutMs")) {
             validateTimeout(cloned.fallbackTimeoutMs, "execution runner material.fallbackTimeoutMs");
         }

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

@@ -54,7 +54,7 @@ export function prepareResolvedExecution(options) {
         ...(options.invocationDefaults ? { invocationDefaults: options.invocationDefaults } : {}),
         ...(options.current ? { current: options.current } : {}),
         engines: executionEngineDefinitionsFromConfig(config),
-        modelMap: options.modelMap ?? loadModelMap().map,
+        modelMap: options.modelMap ?? loadModelMap({ engines: config.engines }).map,
         invocationKind: options.invocationKind,
         ...(options.authorizeTools ? { authorizeTools: options.authorizeTools } : {}),
     });

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

@@ -69,13 +69,25 @@ 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");
+    assertOnlyKeys(record, ["model", "inference", "engine"], source, jsonPath);
+    if (!Object.hasOwn(record, "model") && !Object.hasOwn(record, "inference") && !Object.hasOwn(record, "engine")) {
+        invalid(source, jsonPath, "structured profile must contain model, inference, and/or engine");
+    }
+    if (Object.hasOwn(record, "model") && Object.hasOwn(record, "engine")) {
+        invalid(source, jsonPath, "model and engine cannot both be set; engine is an indirection for the model value");
     }
     const out = {};
     if (Object.hasOwn(record, "model"))
         out.model = requireNonemptyString(record.model, source, `${jsonPath}.model`);
+    if (Object.hasOwn(record, "engine")) {
+        const rawEngine = requireNonemptyString(record.engine, source, `${jsonPath}.engine`);
+        const engine = rawEngine.toLowerCase();
+        assertSafeMapKey(engine, source, `${jsonPath}.engine`);
+        if (!ENGINE_KEY_PATTERN.test(engine)) {
+            invalid(source, `${jsonPath}.engine`, "engine reference must be lowercase kebab-case");
+        }
+        out.engine = engine;
+    }
     if (Object.hasOwn(record, "inference")) {
         if (record.inference === null)
             out.inference = null;
@@ -161,10 +173,21 @@ function mergeProfiles(base, overlay) {
     const out = {};
     if (base?.model !== undefined)
         out.model = base.model;
+    if (base?.engine !== undefined)
+        out.engine = base.engine;
     if (base && Object.hasOwn(base, "inference"))
         out.inference = base.inference;
-    if (next.model !== undefined)
+    // A literal `model` and an `engine` indirection are mutually exclusive within
+    // one layer (enforced at parse time); across layers, whichever the nearer
+    // layer sets replaces the other so the merged profile keeps that invariant.
+    if (next.model !== undefined) {
         out.model = next.model;
+        delete out.engine;
+    }
+    if (next.engine !== undefined) {
+        out.engine = next.engine;
+        delete out.model;
+    }
     if (Object.hasOwn(next, "inference")) {
         out.inference =
             next.inference !== null && next.inference !== undefined && isJsonObject(base?.inference)
@@ -173,14 +196,50 @@ function mergeProfiles(base, overlay) {
     }
     return Object.freeze(out);
 }
-/** Overlay user fields over installed fields, then enforce usable merged profiles. */
-export function mergeModelMapLayers(installed, user) {
+/**
+ * Derive the `{ model, inference }` a model-map profile borrows from a
+ * configured engine (#946). Shared verbatim by
+ * `execution-definitions.ts`'s own execution-defaults derivation
+ * (`engineDefaults`) so the two paths cannot silently diverge. `model` is
+ * copied verbatim from the engine's own config value; it must already be
+ * meaningful for the model-map column's platform (akm does not translate
+ * between an engine's connection and an agent platform's own provider
+ * registry). Only `kind: "llm"` engines contribute inference defaults — an
+ * agent-kind engine's schema carries no temperature/thinking fields.
+ */
+export function engineModelAndInference(engine) {
+    const out = {};
+    if (Object.hasOwn(engine, "model") && engine.model !== undefined)
+        out.model = engine.model;
+    if (engine.kind === "llm") {
+        const inference = {};
+        if (Object.hasOwn(engine, "temperature"))
+            inference.temperature = engine.temperature;
+        if (Object.hasOwn(engine, "maxTokens"))
+            inference.maxTokens = engine.maxTokens;
+        if (Object.hasOwn(engine, "supportsJsonSchema"))
+            inference.supportsJsonSchema = engine.supportsJsonSchema;
+        if (Object.hasOwn(engine, "extraParams"))
+            inference.extraParams = engine.extraParams;
+        if (Object.hasOwn(engine, "contextLength"))
+            inference.contextLength = engine.contextLength;
+        if (Object.hasOwn(engine, "enableThinking"))
+            inference.enableThinking = engine.enableThinking;
+        if (Object.hasOwn(engine, "reasoningEffort"))
+            inference.reasoningEffort = engine.reasoningEffort;
+        if (Object.keys(inference).length > 0)
+            out.inference = inference;
+    }
+    return Object.freeze(out);
+}
+/** Overlay user fields over installed fields, per (alias, column), without resolving `engine` indirection. */
+function mergeRawProfileLayers(installed, user) {
     const aliases = new Map();
     const apply = (layer) => {
-        for (const [alias, engines] of Object.entries(layer.aliases)) {
+        for (const [alias, layerEngines] 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));
+            for (const [engineKey, profile] of Object.entries(layerEngines)) {
+                mergedEngines.set(engineKey, mergeProfiles(mergedEngines.get(engineKey), profile));
             }
             aliases.set(alias, mergedEngines);
         }
@@ -188,14 +247,55 @@ export function mergeModelMapLayers(installed, user) {
     apply(installed);
     if (user)
         apply(user);
+    return aliases;
+}
+/**
+ * The overlaid-but-unresolved profile per (alias, column), before any
+ * `engine` indirection is expanded. `akm models list` (#946) uses this to
+ * report whether a column resolves through a literal `model` or an `engine`
+ * reference — information {@link mergeModelMapLayers} collapses away once it
+ * performs the final resolution.
+ */
+export function mergedModelMapProfiles(installed, user) {
+    const aliases = mergeRawProfileLayers(installed, user);
+    const out = [];
+    for (const [alias, engineProfiles] of aliases)
+        out.push([alias, freezeRecord(engineProfiles)]);
+    return freezeRecord(out);
+}
+/**
+ * Overlay user fields over installed fields, resolve any `engine` indirection
+ * against configured engines, then enforce usable merged profiles.
+ */
+export function mergeModelMapLayers(installed, user, engines) {
+    const aliases = mergeRawProfileLayers(installed, user);
     const resolvedAliases = [];
-    for (const [alias, engines] of aliases) {
+    for (const [alias, engineProfiles] 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");
+        for (const [engineKey, profile] of engineProfiles) {
+            let model = profile.model;
+            let inference = Object.hasOwn(profile, "inference") ? profile.inference : undefined;
+            if (model === undefined && profile.engine !== undefined) {
+                const target = ownValue(engines, profile.engine);
+                if (target === undefined) {
+                    invalid("merged models.json", `$.aliases.${alias}.${engineKey}.engine`, `references unknown engine ${JSON.stringify(profile.engine)}; a usable model is required after overlay`);
+                }
+                const expansion = engineModelAndInference(target);
+                if (expansion.model === undefined) {
+                    invalid("merged models.json", `$.aliases.${alias}.${engineKey}.engine`, `engine ${JSON.stringify(profile.engine)} has no usable model; a usable model is required after overlay`);
+                }
+                model = expansion.model;
+                inference =
+                    inference === undefined
+                        ? expansion.inference
+                        : inference !== null && isJsonObject(expansion.inference)
+                            ? mergeJsonValue(expansion.inference, inference)
+                            : inference;
             }
-            resolvedEngines.push([engine, Object.freeze({ ...profile, model: profile.model })]);
+            if (model === undefined) {
+                invalid("merged models.json", `$.aliases.${alias}.${engineKey}.model`, "a usable model is required after overlay");
+            }
+            resolvedEngines.push([engineKey, Object.freeze(inference !== undefined ? { model, inference } : { model })]);
         }
         resolvedAliases.push([alias, freezeRecord(resolvedEngines)]);
     }
@@ -314,15 +414,18 @@ export function readInstalledModelMapText(options = {}) {
     }
     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 = {}) {
+/** Read and parse the installed authority plus the optional operator overlay, without resolving them. */
+export function loadModelMapLayers(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" });
+    const user = userText !== undefined ? parseModelMapLayer(userText, `user models.json (${userPath})`) : undefined;
+    return Object.freeze({ installed, ...(user ? { user } : {}), userPath, userStatus: user ? "loaded" : "absent" });
+}
+/** Load the installed authority plus the optional operator overlay. */
+export function loadModelMap(options = {}) {
+    const { installed, user, userPath, userStatus } = loadModelMapLayers(options);
+    return Object.freeze({ map: mergeModelMapLayers(installed, user, options.engines), userPath, userStatus });
 }
 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.");