akm-cli 0.9.10 → 0.9.11

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

@@ -1,6 +1,8 @@
 // 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 fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
 import { ConfigError } from "../../core/errors.js";
@@ -22,6 +24,51 @@ function envName(reference) {
     const match = /^\$(?:\{)?([A-Za-z_][A-Za-z0-9_]*)(?:\})?$/.exec(reference);
     return match?.[1];
 }
+/** Expand a leading `~` the same way `loadSetupConfigFromFile` does for `--from <file>`. */
+function expandHomePath(filePath) {
+    return filePath.startsWith("~") ? path.join(os.homedir(), filePath.slice(1)) : filePath;
+}
+/** Trim exactly one trailing newline (`\n` or `\r\n`) — never interior whitespace. */
+function trimTrailingNewline(raw) {
+    return raw.replace(/\r?\n$/, "");
+}
+/**
+ * Read a file-backed credential (#905) at the dispatch boundary. Never
+ * includes the file's content in a thrown message — only the engine name and
+ * path, so a misconfigured `apiKeyFile` cannot leak its (partial) contents
+ * into a log or error report.
+ */
+function readApiKeyFile(engineName, filePath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err instanceof Error ? err.code : undefined;
+        const reason = code === "ENOENT" ? "does not exist" : "could not be read";
+        throw new ConfigError(`Engine "${engineName}" apiKeyFile ${reason}: ${filePath}`, "INVALID_CONFIG_FILE");
+    }
+    const value = trimTrailingNewline(raw);
+    if (value.length === 0) {
+        throw new ConfigError(`Engine "${engineName}" apiKeyFile is empty: ${filePath}`, "INVALID_CONFIG_FILE");
+    }
+    return value;
+}
+/**
+ * Best-effort, non-throwing read of a file-backed credential's current value
+ * (#905), for redaction inventories and health probes that must never fail
+ * just because a value collector ran ahead of the real dispatch — a missing
+ * or empty file is reported by {@link readApiKeyFile} at the actual call.
+ */
+export function lookupApiKeyFileValue(filePath) {
+    try {
+        const value = trimTrailingNewline(fs.readFileSync(filePath, "utf8"));
+        return value.length > 0 ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 function selectedEngineName(config, layers, llmOnly) {
     for (let index = layers.length - 1; index >= 0; index--) {
         const layer = layers[index];
@@ -50,6 +97,11 @@ function resolveCredential(name, engine, config) {
             throw new ConfigError(`Engine "${name}" has an invalid symbolic apiKey reference.`, "INVALID_CONFIG_FILE");
         return { names: [explicit], required: true };
     }
+    // #905: an explicit apiKeyFile is its own credential source — resolved
+    // separately onto `ResolvedLlmUse.apiKeyFile` — so it does not also fall
+    // through to the implicit AKM_ENGINE_<NAME>_API_KEY convention below.
+    if (ownValue(engine, "apiKeyFile") !== undefined)
+        return undefined;
     const specific = `AKM_ENGINE_${name.toUpperCase().replaceAll("-", "_")}_API_KEY`;
     const defaults = ownValue(config, "defaults");
     return (defaults ? ownValue(defaults, "llmEngine") : undefined) === name
@@ -81,6 +133,20 @@ export function resolveCredentialFromEnv(credential, envSource = process.env) {
     }
     return undefined;
 }
+/**
+ * The enforcing credential seam for one resolved LLM engine or SDK fallback
+ * (#905): the symbolic env-var descriptor first (throws if a required one is
+ * missing), then the file-backed alternative when no env descriptor applies.
+ * Call this once per operation — lease acquisition, or direct materialize —
+ * 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) {
+    const envValue = resolveCredentialFromEnv(credential, envSource);
+    if (envValue !== undefined)
+        return envValue;
+    return apiKeyFile !== undefined ? readApiKeyFile(engine, apiKeyFile) : undefined;
+}
 /** Collect materialized engine credentials for output and persistence redaction. */
 export function collectEngineCredentialValues(config, envSource = process.env) {
     const values = new Set();
@@ -92,6 +158,15 @@ export function collectEngineCredentialValues(config, envSource = process.env) {
             if (value)
                 values.add(value);
         }
+        // #905: file-backed credential — best-effort, so a broken apiKeyFile on
+        // one engine never stops redaction from collecting every other engine's
+        // credential too.
+        const apiKeyFile = ownValue(engine, "apiKeyFile");
+        if (apiKeyFile !== undefined) {
+            const value = lookupApiKeyFileValue(expandHomePath(apiKeyFile));
+            if (value)
+                values.add(value);
+        }
     }
     return collectSensitiveValues(values);
 }
@@ -145,14 +220,22 @@ export function resolveLlmEngineUse(config, layers, options = {}) {
         if (connection[key] === undefined)
             delete connection[key];
     }
+    const apiKeyFile = ownValue(engine, "apiKeyFile");
     return {
         engine: name,
         connection: sterileRecord(connection),
         credential: resolveCredential(name, engine, config),
+        ...(apiKeyFile !== undefined ? { apiKeyFile: expandHomePath(apiKeyFile) } : {}),
         timeoutMs: effectiveTimeout(engine, layers, DEFAULT_LLM_TIMEOUT_MS),
     };
 }
-/** Read a resolved symbolic credential only at the runtime dispatch boundary. */
+/**
+ * Inject an already-resolved credential value into a connection. Callers
+ * resolve the value themselves via {@link resolveLlmCredentialValue} (or its
+ * lease-cached equivalent) — this function never reads env or disk itself, so
+ * a frozen `ResolvedLlmUse`/`RunnerSpec` plan object can be materialized
+ * repeatedly without re-triggering I/O per call.
+ */
 export function materializeLlmConnectionWithCredential(resolved, credentialValue) {
     const extraParams = ownValue(resolved.connection, "extraParams");
     if (extraParams !== undefined) {
@@ -167,9 +250,13 @@ export function materializeLlmConnectionWithCredential(resolved, credentialValue
         timeoutMs: resolved.timeoutMs,
     });
 }
-/** Read and inject one resolved symbolic credential at the runtime boundary. */
+/**
+ * Read and inject one resolved credential at the runtime boundary: the
+ * symbolic `$VAR` reference, or the file-backed alternative (#905) when the
+ * engine has no env descriptor.
+ */
 export function materializeLlmConnection(resolved, envSource = process.env) {
-    return materializeLlmConnectionWithCredential(resolved, resolveCredentialFromEnv(resolved.credential, envSource));
+    return materializeLlmConnectionWithCredential(resolved, resolveLlmCredentialValue(resolved.engine, resolved.credential, resolved.apiKeyFile, envSource));
 }
 function lowerAgentEngine(name, engine, config) {
     const harness = getHarness(engine.platform);
@@ -217,6 +304,7 @@ function lowerAgentEngine(name, engine, config) {
             ? {
                 fallbackConnection: fallback.connection,
                 ...(fallback.credential ? { fallbackCredential: fallback.credential } : {}),
+                ...(fallback.apiKeyFile ? { fallbackApiKeyFile: fallback.apiKeyFile } : {}),
                 fallbackTimeoutMs: fallback.timeoutMs,
             }
             : {}),
@@ -237,6 +325,7 @@ export function resolveEngine(name, config) {
             engine: name,
             connection: resolved.connection,
             ...(resolved.credential ? { credential: resolved.credential } : {}),
+            ...(resolved.apiKeyFile ? { apiKeyFile: resolved.apiKeyFile } : {}),
             timeoutMs: resolved.timeoutMs,
         };
     }

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

@@ -210,17 +210,29 @@ function snapshotRunnerSpec(input, options = {}) {
     if (own(cloned, "timeoutMs"))
         validateTimeout(cloned.timeoutMs, "execution runner material.timeoutMs");
     if (kind === "llm") {
-        assertKeys(cloned, ["kind", "engine", "connection", "credential", "timeoutMs"], "execution runner material");
+        assertKeys(cloned, ["kind", "engine", "connection", "credential", "apiKeyFile", "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");
     }
     else if (kind === "agent") {
         assertKeys(cloned, ["kind", "engine", "profile", "timeoutMs"], "execution runner material");
         validateProfile(cloned.profile, "execution runner material.profile");
     }
     else if (kind === "sdk") {
-        assertKeys(cloned, ["kind", "engine", "profile", "fallbackConnection", "fallbackCredential", "fallbackTimeoutMs", "timeoutMs"], "execution runner material");
+        assertKeys(cloned, [
+            "kind",
+            "engine",
+            "profile",
+            "fallbackConnection",
+            "fallbackCredential",
+            "fallbackApiKeyFile",
+            "fallbackTimeoutMs",
+            "timeoutMs",
+        ], "execution runner material");
         validateProfile(cloned.profile, "execution runner material.profile");
         if (own(cloned, "fallbackConnection")) {
             validateConnection(cloned.fallbackConnection, "execution runner material.fallbackConnection", !options.allowMissingSdkFallbackModel);
@@ -228,6 +240,7 @@ function snapshotRunnerSpec(input, options = {}) {
         if (own(cloned, "fallbackCredential")) {
             validateCredential(cloned.fallbackCredential, "execution runner material.fallbackCredential");
         }
+        validateOptionalString(cloned, "fallbackApiKeyFile", "execution runner material");
         if (own(cloned, "fallbackTimeoutMs")) {
             validateTimeout(cloned.fallbackTimeoutMs, "execution runner material.fallbackTimeoutMs");
         }

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 { lookupCredentialFromEnv, materializeLlmConnection, materializeLlmConnectionWithCredential, resolveCredentialFromEnv, } from "./engine-resolution.js";
+import { lookupApiKeyFileValue, lookupCredentialFromEnv, materializeLlmConnection, materializeLlmConnectionWithCredential, resolveLlmCredentialValue, } from "./engine-resolution.js";
 import { materializeLlmRunnerConnection, materializeLlmRunnerConnectionWithCredential, } from "./runner.js";
 import { runAgent } from "./spawn.js";
 const liveRunnerDispatchLeases = new WeakMap();
@@ -78,6 +78,7 @@ function runnerLeaseBinding(spec) {
                 endpoint: spec.connection.endpoint,
                 provider: spec.connection.provider ?? null,
                 credential: credentialBinding(spec.credential),
+                apiKeyFile: spec.apiKeyFile ?? null,
             });
         case "agent":
             return JSON.stringify({
@@ -99,6 +100,7 @@ function runnerLeaseBinding(spec) {
                 fallbackEndpoint: spec.fallbackConnection?.endpoint ?? null,
                 fallbackProvider: spec.fallbackConnection?.provider ?? null,
                 fallbackCredential: credentialBinding(spec.fallbackCredential),
+                fallbackApiKeyFile: spec.fallbackApiKeyFile ?? null,
             });
         default:
             return assertNever(spec);
@@ -131,8 +133,12 @@ export function acquireRunnerDispatchLease(spec, envSource = process.env) {
             return typeof property === "string" ? environment.read(property) : undefined;
         },
     });
-    const primaryCredential = spec.kind === "llm" ? resolveCredentialFromEnv(spec.credential, credentialSource) : undefined;
-    const fallbackCredential = spec.kind === "sdk" ? resolveCredentialFromEnv(spec.fallbackCredential, credentialSource) : undefined;
+    const primaryCredential = spec.kind === "llm"
+        ? resolveLlmCredentialValue(spec.engine, spec.credential, spec.apiKeyFile, credentialSource)
+        : undefined;
+    const fallbackCredential = spec.kind === "sdk"
+        ? resolveLlmCredentialValue(spec.engine, spec.fallbackCredential, spec.fallbackApiKeyFile, credentialSource)
+        : undefined;
     const handle = Object.create(null);
     Object.defineProperty(handle, "toJSON", {
         configurable: false,
@@ -217,6 +223,12 @@ export function collectDispatchSensitiveValues(spec, opts, envSource = opts.envS
         add(lookupCredentialFromEnv(spec.credential, envSource));
     if (spec.kind === "sdk")
         add(lookupCredentialFromEnv(spec.fallbackCredential, envSource));
+    // #905: a file-backed credential is read at dispatch, so it must be in the
+    // scrub set for the same reason the env-backed one is.
+    if (spec.kind === "llm" && spec.apiKeyFile)
+        add(lookupApiKeyFileValue(spec.apiKeyFile));
+    if (spec.kind === "sdk" && spec.fallbackApiKeyFile)
+        add(lookupApiKeyFileValue(spec.fallbackApiKeyFile));
     if (spec.kind !== "llm") {
         for (const value of Object.values(spec.profile.env ?? {}))
             add(value);
@@ -315,6 +327,7 @@ export async function executeRunner(spec, prompt, opts, seams = {}, lease) {
                     engine: spec.engine ?? "unnamed-sdk-fallback",
                     connection: spec.fallbackConnection,
                     ...(spec.fallbackCredential ? { credential: spec.fallbackCredential } : {}),
+                    ...(spec.fallbackApiKeyFile ? { apiKeyFile: spec.fallbackApiKeyFile } : {}),
                     timeoutMs: spec.fallbackTimeoutMs !== undefined
                         ? spec.fallbackTimeoutMs
                         : Object.hasOwn(spec.fallbackConnection, "timeoutMs")

package/dist/integrations/agent/runner.js

@@ -8,6 +8,7 @@ export function materializeLlmRunnerConnection(runner) {
         engine: runner.engine,
         connection: runner.connection,
         ...(runner.credential ? { credential: runner.credential } : {}),
+        ...(runner.apiKeyFile ? { apiKeyFile: runner.apiKeyFile } : {}),
         timeoutMs: runner.timeoutMs ?? null,
     });
 }
@@ -17,6 +18,7 @@ export function materializeLlmRunnerConnectionWithCredential(runner, credentialV
         engine: runner.engine,
         connection: runner.connection,
         ...(runner.credential ? { credential: runner.credential } : {}),
+        ...(runner.apiKeyFile ? { apiKeyFile: runner.apiKeyFile } : {}),
         timeoutMs: runner.timeoutMs ?? null,
     }, credentialValue);
 }

package/dist/output/shapes/passthrough.js

@@ -70,6 +70,7 @@ const PASSTHROUGH_COMMANDS = [
     "task-run",
     "task-sync",
     "task-sync-dry-run",
+    "task-validate",
     "update",
     "upgrade",
     "workflow-abandon",