akm-cli 0.9.14 → 0.9.15-beta.1

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.");

package/dist/integrations/agent/prompts.js

@@ -25,6 +25,7 @@
  * `frontmatter` is optional — the proposal queue parses it from `content`
  * during validation. We carry it through if the agent supplies it.
  */
+import reflectFeedbackFraming from "../../assets/prompts/reflect-feedback-framing.md" with { type: "text" };
 import reflectLlmFramedContract from "../../assets/prompts/reflect-llm-framed-contract.md" with { type: "text" };
 import reflectLlmSchemaContract from "../../assets/prompts/reflect-llm-schema-contract.md" with { type: "text" };
 import reflectOutputRepair from "../../assets/prompts/reflect-output-repair.md" with { type: "text" };
@@ -56,6 +57,25 @@ function hintForType(type) {
 function knownTypeList() {
     return [...placementTypes()].sort().join(", ");
 }
+/**
+ * Default cap (in characters) on the asset content injected into
+ * {@link buildReflectPrompt}, and the floor a caller-supplied
+ * {@link ReflectPromptInput.contentBudgetChars} is never allowed to go below.
+ * Exists to stay well under OS ARG_MAX when the prompt is passed as a CLI
+ * argument to opencode/claude — large assets (wiki snapshots, long runbooks)
+ * would otherwise trigger E2BIG on posix_spawn. Agent/SDK runners always use
+ * this flat value; the direct-LLM path can raise it per #952 (see the reflect
+ * dispatch site in `src/commands/improve/reflect.ts`).
+ */
+export const REFLECT_CONTENT_CAP = 12_000;
+/**
+ * Marker appended to truncated asset content when it exceeds the active
+ * content budget (#952). Exported so `sanitizeReflectPayload` can detect a
+ * model that echoed this notice back into its rewrite instead of proposing
+ * real content, and so the output contracts can reference the exact string
+ * to forbid.
+ */
+export const REFLECT_TRUNCATION_MARKER = "... [truncated — focus on the visible portion]";
 /**
  * Common envelope every prompt asks the agent to honour when NO draft file
  * path is available. The wrapper code uses `JSON.parse(stdout)` to extract
@@ -87,6 +107,7 @@ function fileWriteContract(draftFilePath) {
         `Write the complete improved asset content to: ${draftFilePath}`,
         "Use your file-editing tools to create or overwrite that file.",
         "Do NOT output JSON to stdout. Do NOT print the file contents. Just write the file.",
+        `Never include the text "${REFLECT_TRUNCATION_MARKER}" or any other content from outside the provided asset content in the file you write.`,
         "When done, output a single line on stdout: DRAFT_WRITTEN confidence=<0.0-1.0>",
         "`confidence` is REQUIRED and must be your honest self-rated [0, 1] score for this proposal:",
         "  • 0.90+ — fixes a real defect or adds load-bearing missing content; reviewer would clearly accept.",
@@ -124,10 +145,14 @@ export function reflectLlmResponseContract(mode, targetScoped) {
             .replace("{{FIELD_RULE}}", targetScoped
             ? "The response has exactly the required fields `content`, `confidence`, and `frontmatterPatch`; do not echo `ref` or arbitrary `frontmatter`."
             : "The response has exactly the required fields `ref`, `content`, `confidence`, and `frontmatterPatch`; `ref` must identify the selected asset.")
+            .replaceAll("{{TRUNCATION_MARKER}}", REFLECT_TRUNCATION_MARKER)
             .trim();
     }
     const refLine = targetScoped ? "" : "AKM_REFLECT_REF: <selected asset ref>\n";
-    return reflectLlmFramedContract.replace("{{REF_LINE}}", refLine).trim();
+    return reflectLlmFramedContract
+        .replace("{{REF_LINE}}", refLine)
+        .replaceAll("{{TRUNCATION_MARKER}}", REFLECT_TRUNCATION_MARKER)
+        .trim();
 }
 export function buildReflectOutputRepairPrompt(mode, targetScoped) {
     return reflectOutputRepair.replace("{{OUTPUT_CONTRACT}}", reflectLlmResponseContract(mode, targetScoped)).trim();
@@ -194,6 +219,10 @@ export function buildReflectPrompt(input) {
     }
     // Change 3 & 4 — feedback moved before asset content; missing else branch added
     if (input.feedback && input.feedback.length > 0) {
+        // #952 — feedback lines are unverified reports, not verified facts. Without
+        // this caveat, models fabricated whole new sections asserting whatever a
+        // feedback line claimed (invented incident dates, ports, disk layouts).
+        sections.push(reflectFeedbackFraming.trim());
         sections.push("Recent feedback / signals:");
         for (const line of input.feedback)
             sections.push(`- ${line}`);
@@ -238,17 +267,20 @@ export function buildReflectPrompt(input) {
         }
     }
     if (input.assetContent?.trim()) {
-        // Cap at 12 000 chars to stay well under OS ARG_MAX when the prompt is
-        // passed as a CLI argument to opencode/claude. Large assets (wiki snapshots,
-        // long runbooks) would otherwise trigger E2BIG on posix_spawn.
-        const REFLECT_CONTENT_CAP = 12_000;
+        // Cap defaults to REFLECT_CONTENT_CAP (12 000 chars) to stay well under OS
+        // ARG_MAX when the prompt is passed as a CLI argument to opencode/claude
+        // — large assets (wiki snapshots, long runbooks) would otherwise trigger
+        // E2BIG on posix_spawn. Direct-LLM callers never touch argv, so they may
+        // pass a larger, context-aware `contentBudgetChars` (#952); it is never
+        // allowed below the flat floor, which the caller enforces before calling in.
+        const contentCap = input.contentBudgetChars ?? REFLECT_CONTENT_CAP;
         const body = input.assetContent.trimEnd();
-        const truncated = body.length > REFLECT_CONTENT_CAP;
+        const truncated = body.length > contentCap;
         sections.push(truncated
-            ? `Current asset content (first ${REFLECT_CONTENT_CAP} chars — full asset is ${body.length} chars):`
+            ? `Current asset content (first ${contentCap} chars — full asset is ${body.length} chars):`
             : "Current asset content (verbatim):");
         sections.push("```");
-        sections.push(truncated ? `${body.slice(0, REFLECT_CONTENT_CAP)}\n... [truncated — focus on the visible portion]` : body);
+        sections.push(truncated ? `${body.slice(0, contentCap)}\n${REFLECT_TRUNCATION_MARKER}` : body);
         sections.push("```");
     }
     else if (input.ref) {

package/dist/integrations/agent/runner-dispatch.js

@@ -20,7 +20,7 @@ import { assertNever } from "../../core/assert.js";
 import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveText, redactSensitiveValue, } from "../../core/redaction.js";
 import { spawnEnvNamesFor } from "../../core/spawn-env.js";
 import { closeServer as disposeOpencodeSdkServers, opencodeSdkServerEnvironmentNames, runOpencodeSdk, } from "../harnesses/opencode-sdk/sdk-runner.js";
-import { lookupApiKeyFileValue, lookupCredentialFromEnv, materializeLlmConnection, materializeLlmConnectionWithCredential, resolveLlmCredentialValue, } from "./engine-resolution.js";
+import { lookupApiKeyFileValue, lookupApiKeySecretRefValue, lookupCredentialFromEnv, materializeLlmConnection, materializeLlmConnectionWithCredential, resolveLlmCredentialValue, } from "./engine-resolution.js";
 import { materializeLlmRunnerConnection, materializeLlmRunnerConnectionWithCredential, } from "./runner.js";
 import { runAgent } from "./spawn.js";
 const liveRunnerDispatchLeases = new WeakMap();
@@ -134,10 +134,10 @@ export function acquireRunnerDispatchLease(spec, envSource = process.env) {
         },
     });
     const primaryCredential = spec.kind === "llm"
-        ? resolveLlmCredentialValue(spec.engine, spec.credential, spec.apiKeyFile, credentialSource)
+        ? resolveLlmCredentialValue(spec.engine, spec.credential, spec.apiKeyFile, spec.apiKeySecretRef, credentialSource)
         : undefined;
     const fallbackCredential = spec.kind === "sdk"
-        ? resolveLlmCredentialValue(spec.engine, spec.fallbackCredential, spec.fallbackApiKeyFile, credentialSource)
+        ? resolveLlmCredentialValue(spec.engine, spec.fallbackCredential, spec.fallbackApiKeyFile, spec.fallbackApiKeySecretRef, credentialSource)
         : undefined;
     const handle = Object.create(null);
     Object.defineProperty(handle, "toJSON", {
@@ -229,6 +229,12 @@ export function collectDispatchSensitiveValues(spec, opts, envSource = opts.envS
         add(lookupApiKeyFileValue(spec.apiKeyFile));
     if (spec.kind === "sdk" && spec.fallbackApiKeyFile)
         add(lookupApiKeyFileValue(spec.fallbackApiKeyFile));
+    // #953: a secret-store-backed credential is read at dispatch too — same
+    // best-effort scrub-set inclusion rationale.
+    if (spec.kind === "llm" && spec.apiKeySecretRef)
+        add(lookupApiKeySecretRefValue(spec.apiKeySecretRef));
+    if (spec.kind === "sdk" && spec.fallbackApiKeySecretRef)
+        add(lookupApiKeySecretRefValue(spec.fallbackApiKeySecretRef));
     if (spec.kind !== "llm") {
         for (const value of Object.values(spec.profile.env ?? {}))
             add(value);

package/dist/integrations/agent/runner.js

@@ -9,6 +9,7 @@ export function materializeLlmRunnerConnection(runner) {
         connection: runner.connection,
         ...(runner.credential ? { credential: runner.credential } : {}),
         ...(runner.apiKeyFile ? { apiKeyFile: runner.apiKeyFile } : {}),
+        ...(runner.apiKeySecretRef ? { apiKeySecretRef: runner.apiKeySecretRef } : {}),
         timeoutMs: runner.timeoutMs ?? null,
     });
 }
@@ -19,6 +20,7 @@ export function materializeLlmRunnerConnectionWithCredential(runner, credentialV
         connection: runner.connection,
         ...(runner.credential ? { credential: runner.credential } : {}),
         ...(runner.apiKeyFile ? { apiKeyFile: runner.apiKeyFile } : {}),
+        ...(runner.apiKeySecretRef ? { apiKeySecretRef: runner.apiKeySecretRef } : {}),
         timeoutMs: runner.timeoutMs ?? null,
     }, credentialValue);
 }

package/dist/llm/client.js

@@ -290,12 +290,17 @@ async function chatCompletionAttemptOnce(config, messages, options, timeoutMs, i
             },
         }
         : {};
+    // #949: which of these two wire forms a backend honors is a fact about the
+    // backend (and any gateway in front of it), not about akm's own `provider`
+    // label — a llama.cpp build honors chat_template_kwargs, a bare
+    // `enable_thinking` is honored by nothing observed, and a gateway
+    // (freellmapi, Bifrost) can drop either one depending on how it was built.
+    // Send both whenever thinking is explicitly resolved so the same engine
+    // block keeps working across a direct vhost or any gateway in front of it.
     const resolvedEnableThinking = options?.enableThinking ?? config.enableThinking;
     const thinkingParams = resolvedEnableThinking === undefined
         ? {}
-        : config.provider === "vllm"
-            ? { chat_template_kwargs: { enable_thinking: resolvedEnableThinking } }
-            : { enable_thinking: resolvedEnableThinking };
+        : { chat_template_kwargs: { enable_thinking: resolvedEnableThinking }, enable_thinking: resolvedEnableThinking };
     const reasoningEffortParams = config.reasoningEffort === undefined ? {} : { reasoning_effort: config.reasoningEffort };
     const requestBody = JSON.stringify({
         model: config.model,