akm-cli 0.9.16 → 0.9.17-alpha.10

package/dist/indexer/walk/walker.js

@@ -169,10 +169,9 @@ function isInsideGitRepo(dir) {
 /**
  * Recursively collect every `.md` file under `root`.
  *
- * Shared by graph-extraction and memory-inference so the walk logic lives in
- * exactly one place. Mirrors the `complete` tracking of the other walkers in
- * this file: a directory that cannot be read makes the result incomplete
- * instead of silently looking like a clean, empty scan.
+ * Used by memory-inference. Mirrors the `complete` tracking of the other
+ * walkers in this file: a directory that cannot be read makes the result
+ * incomplete instead of silently looking like a clean, empty scan.
  */
 export function walkMarkdownFiles(root) {
     const files = [];

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

@@ -3,72 +3,55 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { defaultWhich } from "./detect.js";
 import { OPENCODE_SDK_SERVER_BIN } from "./profiles.js";
-/**
- * Engine name used for the synthesized entry. Matches the platform id so it
- * reads correctly in `akm workflow status`, frozen plans, and error messages.
- * A user-configured engine of the same name is preferred over synthesizing.
- */
+/** Engine name used for the synthesized entry; matches the platform id. */
 export const FALLBACK_ENGINE_NAME = "opencode-sdk";
 /** Announcement text, surfaced once per run/dispatch. */
 export const FALLBACK_ANNOUNCEMENT = `No engine is configured; falling back to \`${FALLBACK_ENGINE_NAME}\` via the ` +
     `\`${OPENCODE_SDK_SERVER_BIN}\` binary on PATH — provider, model, and auth come ` +
     "from opencode's own configuration. " +
     "Run `akm setup`, or set `defaults.engine`, to choose explicitly.";
-/**
- * Failure suffix for every surface that needs an engine and found none.
- * Owned HERE, beside the probe whose outcome it describes: the probe follows a
- * configured `bin` when one is pinned, so a consumer restating "not on PATH"
- * would misdescribe a missing absolute path.
- */
+/** Failure suffix for every surface that needs an engine and found none. */
 export const NO_ENGINE_MESSAGE_SUFFIX = `has no selected engine, and no usable \`${OPENCODE_SDK_SERVER_BIN}\` binary was found to fall back to.`;
-/**
- * Guidance used when the fallback itself is unavailable.
- *
- * The opencode route names a BINARY install, not `npm i @opencode-ai/sdk`:
- * that package is an HTTP client with no dependencies and cannot serve
- * anything on its own (see the module doc).
- */
+/** Guidance used when the fallback itself is unavailable. */
 export const NO_ENGINE_REMEDY = "Run `akm setup` to detect an installed agent, or set one explicitly: " +
     '`akm config set engines.claude \'{"kind":"agent","platform":"claude"}\'` ' +
     "then `akm config set defaults.engine claude`. " +
     `Installing the \`${OPENCODE_SDK_SERVER_BIN}\` binary also works ` +
     "(`npm i -g opencode-ai`) — akm falls back to it automatically.";
 /**
- * Return a config whose `defaults.engine` resolves, applying the implicit
- * `opencode-sdk` fallback when it does not and an opencode binary is present.
- *
- * Pure with respect to the input: never mutates `config`. Returns the input
- * object identity unchanged when no fallback is needed, so callers can cheaply
- * detect the common case.
+ * The fallback engine when its `opencode` binary is present: an
+ * operator-configured `opencode-sdk` entry (whose pinned `bin`, possibly
+ * outside PATH, is what gets probed), else a bare opencode-sdk agent engine.
+ */
+export function fallbackEngineConfig(config, whichFn = defaultWhich) {
+    const existing = config.engines?.[FALLBACK_ENGINE_NAME];
+    const bin = existing?.kind === "agent" ? existing.bin : undefined;
+    if (!whichFn(bin ?? OPENCODE_SDK_SERVER_BIN))
+        return undefined;
+    return existing ?? { kind: "agent", platform: "opencode-sdk" };
+}
+/**
+ * For diagnostics that report the effective engine: a config whose
+ * `defaults.engine` resolves, with the implicit `opencode-sdk` fallback when it
+ * does not and an opencode binary is present. Never mutates `config`; returns
+ * the same object when no fallback is needed.
  */
 export function withEngineFallback(config, whichFn = defaultWhich) {
     if (config.defaults?.engine)
         return { config };
-    // An operator-configured engine of this name wins over a synthesized one —
-    // theirs may carry a model, an llmEngine fallback, or a pinned bin. Probe
-    // THAT bin rather than the bare command: a configured absolute path outside
-    // PATH is still a usable engine, and reporting it as missing would contradict
-    // the operator-configured-wins rule.
-    const existing = config.engines?.[FALLBACK_ENGINE_NAME];
-    if (!whichFn(existing?.bin ?? OPENCODE_SDK_SERVER_BIN))
+    const engine = fallbackEngineConfig(config, whichFn);
+    if (!engine)
         return { config };
-    const engines = existing
-        ? config.engines
-        : { ...(config.engines ?? {}), [FALLBACK_ENGINE_NAME]: { kind: "agent", platform: "opencode-sdk" } };
     return {
         config: {
             ...config,
-            engines,
+            engines: { ...(config.engines ?? {}), [FALLBACK_ENGINE_NAME]: engine },
             defaults: { ...(config.defaults ?? {}), engine: FALLBACK_ENGINE_NAME },
         },
         fallbackEngineName: FALLBACK_ENGINE_NAME,
     };
 }
-/**
- * The announcement, but only when the fallback candidate is the engine that
- * actually won selection. Returns `undefined` otherwise, so an explicitly
- * selected engine never triggers a claim that opencode supplied the model.
- */
+/** The announcement, but only when the fallback candidate is the engine that actually won selection. */
 export function fallbackAnnouncement(fallbackEngineName, selectedEngineName) {
     if (!fallbackEngineName || selectedEngineName !== fallbackEngineName)
         return undefined;

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

@@ -14,21 +14,23 @@ 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";
-function hasOwn(value, key) {
-    return Object.hasOwn(value, key);
-}
-function ownValue(value, key) {
-    return hasOwn(value, key) ? value[key] : undefined;
-}
-function sterileRecord(value) {
-    return Object.assign(Object.create(null), value);
-}
+import { getBuiltinAgentProfile, OPENCODE_SDK_SERVER_BIN } from "./profiles.js";
+const LLM_CONNECTION_FIELDS = [
+    "provider",
+    "endpoint",
+    "model",
+    "temperature",
+    "maxTokens",
+    "supportsJsonSchema",
+    "extraParams",
+    "contextLength",
+    "enableThinking",
+    "reasoningEffort",
+];
 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;
 }
@@ -36,12 +38,7 @@ function expandHomePath(filePath) {
 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.
- */
+/** Read a file-backed credential; errors name the engine and path, never the contents. */
 function readApiKeyFile(engineName, filePath) {
     let raw;
     try {
@@ -58,12 +55,7 @@ function readApiKeyFile(engineName, filePath) {
     }
     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.
- */
+/** Best-effort, non-throwing read of a file-backed credential for redaction and health. */
 export function lookupApiKeyFileValue(filePath) {
     try {
         const value = trimTrailingNewline(fs.readFileSync(filePath, "utf8"));
@@ -73,13 +65,7 @@ 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.
- */
+/** Best-effort, non-throwing read of a secret-store credential for redaction and health. */
 export function lookupApiKeySecretRefValue(ref) {
     try {
         return resolveSecret(ref, resolveSecretFromStore);
@@ -90,52 +76,39 @@ export function lookupApiKeySecretRefValue(ref) {
 }
 function selectedEngineName(config, layers, llmOnly) {
     for (let index = layers.length - 1; index >= 0; index--) {
-        const layer = layers[index];
-        if (!layer)
-            continue;
-        const engine = ownValue(layer, "engine");
+        const engine = layers[index]?.engine;
         if (engine !== undefined)
             return engine;
     }
-    const defaults = ownValue(config, "defaults");
-    return defaults ? ownValue(defaults, llmOnly ? "llmEngine" : "engine") : undefined;
+    return llmOnly ? config.defaults?.llmEngine : config.defaults?.engine;
 }
-function resolveEngineConfig(name, config) {
-    const engines = ownValue(config, "engines");
-    const engine = engines && hasOwn(engines, name) ? engines[name] : undefined;
-    if (!engine) {
+/** The configured engine of this name; an unconfigured name is an error. */
+export function configuredEngine(name, config) {
+    const engine = config.engines && Object.hasOwn(config.engines, name) ? config.engines[name] : undefined;
+    if (!engine)
         throw new ConfigError(`Engine "${name}" is not configured.`, "INVALID_CONFIG_FILE");
-    }
     return engine;
 }
 function resolveCredential(name, engine, config) {
-    const apiKey = ownValue(engine, "apiKey");
-    if (apiKey !== undefined) {
-        const explicit = envName(apiKey);
+    if (engine.apiKey !== undefined) {
+        const explicit = envName(engine.apiKey);
         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))
+        // A secret-store reference is carried as `apiKeySecretRef` instead.
+        if (SECRET_STORE_REFERENCE_PATTERN.test(engine.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
-    // through to the implicit AKM_ENGINE_<NAME>_API_KEY convention below.
-    if (ownValue(engine, "apiKeyFile") !== undefined)
+    // An explicit apiKeyFile is its own credential source; it does not also
+    // fall through to the implicit AKM_ENGINE_<NAME>_API_KEY convention.
+    if (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
+    return config.defaults?.llmEngine === name
         ? { names: [specific, "AKM_LLM_API_KEY"], required: false }
         : { names: [specific], required: false };
 }
-/**
- * Lookup-only credential projection used by redaction inventories. Returns the
- * first non-empty trimmed value without enforcing a required descriptor.
- */
+/** Lookup-only credential projection used by redaction inventories. */
 export function lookupCredentialFromEnv(credential, envSource = process.env) {
     for (const name of credential?.names ?? []) {
         const candidate = envSource[name]?.trim();
@@ -144,10 +117,7 @@ export function lookupCredentialFromEnv(credential, envSource = process.env) {
     }
     return undefined;
 }
-/**
- * The enforcing env-credential seam. Live and frozen dispatch use the same
- * ordered lookup; a missing required descriptor names its primary variable.
- */
+/** The enforcing env-credential lookup; a missing required descriptor names its primary variable. */
 export function resolveCredentialFromEnv(credential, envSource = process.env) {
     const value = lookupCredentialFromEnv(credential, envSource);
     if (value)
@@ -158,12 +128,9 @@ 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.
+ * Resolve one LLM credential value at the dispatch boundary: the env
+ * descriptor first, then the file-backed value, then the secret-store
+ * reference. Nothing before dispatch reads any of them.
  */
 export function resolveLlmCredentialValue(engine, credential, apiKeyFile, apiKeySecretRef, envSource = process.env) {
     const envValue = resolveCredentialFromEnv(credential, envSource);
@@ -171,25 +138,12 @@ export function resolveLlmCredentialValue(engine, credential, apiKeyFile, apiKey
         return envValue;
     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`.
+ * Non-throwing credential-presence check for `akm health` and improve's
+ * strategy probe. Names WHICH env var / file / secret reference is missing,
+ * never its value; a broken source is reported by the real dispatch.
  */
 export function describeLlmCredentialAvailability(resolved, env = process.env) {
     if (resolved.credential?.required) {
@@ -218,18 +172,13 @@ export function describeLlmCredentialAvailability(resolved, env = process.env) {
     }
     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. */
+/** Collect every configured engine's current credential value for output and persistence redaction. */
 export function collectEngineCredentialValues(config, envSource = process.env) {
     const values = new Set();
-    for (const [name, engine] of Object.entries(ownValue(config, "engines") ?? {})) {
+    for (const [name, engine] of Object.entries(config.engines ?? {})) {
         if (engine.kind !== "llm")
             continue;
         for (const envVar of resolveCredential(name, engine, config)?.names ?? []) {
@@ -237,19 +186,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));
+        // File and secret-store lookups are best-effort so one broken engine never
+        // stops redaction from collecting every other engine's value.
+        if (engine.apiKeyFile !== undefined) {
+            const value = lookupApiKeyFileValue(expandHomePath(engine.apiKeyFile));
             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 (engine.apiKey !== undefined && SECRET_STORE_REFERENCE_PATTERN.test(engine.apiKey)) {
+            const value = lookupApiKeySecretRefValue(engine.apiKey);
             if (value)
                 values.add(value);
         }
@@ -258,27 +203,17 @@ export function collectEngineCredentialValues(config, envSource = process.env) {
 }
 function effectiveTimeout(engine, layers, fallback) {
     for (let index = layers.length - 1; index >= 0; index--) {
-        if (hasOwn(layers[index] ?? {}, "timeoutMs"))
-            return layers[index]?.timeoutMs ?? null;
+        const layer = layers[index];
+        if (layer && Object.hasOwn(layer, "timeoutMs"))
+            return layer.timeoutMs ?? null;
     }
-    return hasOwn(engine, "timeoutMs") ? (engine.timeoutMs ?? null) : fallback;
+    return Object.hasOwn(engine, "timeoutMs") ? (engine.timeoutMs ?? null) : fallback;
 }
 function rawLlmConnection(engine) {
-    const connection = {
-        provider: ownValue(engine, "provider"),
-        endpoint: ownValue(engine, "endpoint"),
-        model: ownValue(engine, "model"),
-        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"),
-    };
-    for (const key of Object.keys(connection)) {
-        if (connection[key] === undefined)
-            delete connection[key];
+    const connection = {};
+    for (const key of LLM_CONNECTION_FIELDS) {
+        if (engine[key] !== undefined)
+            connection[key] = engine[key];
     }
     return connection;
 }
@@ -289,11 +224,10 @@ export function resolveLlmEngineUse(config, layers, options = {}) {
             return undefined;
         throw new ConfigError("No LLM engine is selected. Set defaults.llmEngine or specify engine.", "LLM_NOT_CONFIGURED");
     }
-    const engine = resolveEngineConfig(name, config);
+    const engine = configuredEngine(name, config);
     if (engine.kind !== "llm") {
-        const defaults = ownValue(config, "defaults");
-        const fallbackName = ownValue(engine, "llmEngine") ?? (defaults ? ownValue(defaults, "llmEngine") : undefined);
-        const fallbackEngine = fallbackName ? resolveEngineConfig(fallbackName, config) : undefined;
+        const fallbackName = engine.llmEngine ?? config.defaults?.llmEngine;
+        const fallbackEngine = fallbackName ? configuredEngine(fallbackName, config) : undefined;
         if (!fallbackEngine || fallbackEngine.kind !== "llm") {
             if (options.optional)
                 return undefined;
@@ -308,55 +242,41 @@ export function resolveLlmEngineUse(config, layers, options = {}) {
     }
     let connection = rawLlmConnection(engine);
     for (const layer of layers) {
-        const llm = ownValue(layer, "llm");
-        const model = ownValue(layer, "model");
-        if (llm)
-            connection = deepMergeConfig(connection, llm);
-        if (model !== undefined)
-            connection.model = model;
+        if (layer.llm)
+            connection = deepMergeConfig(connection, layer.llm);
+        if (layer.model !== undefined)
+            connection.model = layer.model;
     }
     for (const key of Object.keys(connection)) {
         if (connection[key] === undefined)
             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;
+    const apiKeySecretRef = engine.apiKey !== undefined && SECRET_STORE_REFERENCE_PATTERN.test(engine.apiKey) ? engine.apiKey : undefined;
     return {
         engine: name,
-        connection: sterileRecord(connection),
+        connection: connection,
         credential: resolveCredential(name, engine, config),
-        ...(apiKeyFile !== undefined ? { apiKeyFile: expandHomePath(apiKeyFile) } : {}),
+        ...(engine.apiKeyFile !== undefined ? { apiKeyFile: expandHomePath(engine.apiKeyFile) } : {}),
         ...(apiKeySecretRef !== undefined ? { apiKeySecretRef } : {}),
         timeoutMs: effectiveTimeout(engine, layers, DEFAULT_LLM_TIMEOUT_MS),
     };
 }
-/**
- * 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.
- */
+/** Inject an already-resolved credential value into a connection; reads nothing itself. */
 export function materializeLlmConnectionWithCredential(resolved, credentialValue) {
-    const extraParams = ownValue(resolved.connection, "extraParams");
+    const extraParams = resolved.connection.extraParams;
     if (extraParams !== undefined) {
         const issue = validateExtraParams(extraParams)[0];
         if (issue) {
             throw new ConfigError(formatExtraParamsIssue(`Engine "${resolved.engine}" extraParams`, issue), "INVALID_CONFIG_FILE");
         }
     }
-    return sterileRecord({
+    return {
         ...resolved.connection,
         ...(credentialValue ? { apiKey: credentialValue } : {}),
         timeoutMs: resolved.timeoutMs,
-    });
+    };
 }
-/**
- * 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.
- */
+/** Read and inject one resolved credential at the runtime boundary. */
 export function materializeLlmConnection(resolved, envSource = process.env) {
     return materializeLlmConnectionWithCredential(resolved, resolveLlmCredentialValue(resolved.engine, resolved.credential, resolved.apiKeyFile, resolved.apiKeySecretRef, envSource));
 }
@@ -368,33 +288,29 @@ function lowerAgentEngine(name, engine, config) {
     const platform = harness.id;
     const sdk = platform === "opencode-sdk";
     const builtin = getBuiltinAgentProfile(platform);
-    const bin = ownValue(engine, "bin");
-    const args = ownValue(engine, "args");
-    const workspace = ownValue(engine, "workspace");
-    const model = ownValue(engine, "model");
-    const profile = sterileRecord({
+    const profile = {
         name,
         platform,
         personaChannel: sdk ? "native" : (harness.agentBuilder?.personaChannel ?? "prompt"),
-        bin: bin ?? builtin?.bin ?? (sdk ? "opencode" : platform),
-        args: args ?? builtin?.args ?? [],
+        bin: engine.bin ?? builtin?.bin ?? (sdk ? OPENCODE_SDK_SERVER_BIN : platform),
+        args: engine.args ?? builtin?.args ?? [],
         stdio: "captured",
         ...(builtin?.env ? { env: builtin.env } : {}),
         envPassthrough: builtin?.envPassthrough ?? [],
         parseOutput: "text",
-        ...(workspace ? { workspace: path.resolve(workspace) } : {}),
-        ...(model ? { model } : {}),
-    });
+        ...(engine.workspace ? { workspace: path.resolve(engine.workspace) } : {}),
+        ...(engine.model ? { model: engine.model } : {}),
+    };
+    const ownTimeout = Object.hasOwn(engine, "timeoutMs") ? (engine.timeoutMs ?? null) : undefined;
     if (!sdk) {
         return {
             kind: "agent",
             engine: name,
             profile,
-            timeoutMs: hasOwn(engine, "timeoutMs") ? (engine.timeoutMs ?? null) : DEFAULT_AGENT_TIMEOUT_MS,
+            timeoutMs: ownTimeout !== undefined ? ownTimeout : DEFAULT_AGENT_TIMEOUT_MS,
         };
     }
-    const defaults = ownValue(config, "defaults");
-    const fallbackName = ownValue(engine, "llmEngine") ?? (defaults ? ownValue(defaults, "llmEngine") : undefined);
+    const fallbackName = engine.llmEngine ?? config.defaults?.llmEngine;
     const fallback = fallbackName
         ? resolveLlmEngineUse(config, [{ engine: fallbackName }], { optional: true })
         : undefined;
@@ -411,27 +327,21 @@ function lowerAgentEngine(name, engine, config) {
                 fallbackTimeoutMs: fallback.timeoutMs,
             }
             : {}),
-        timeoutMs: hasOwn(engine, "timeoutMs")
-            ? (engine.timeoutMs ?? null)
-            : (fallback?.timeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS),
+        timeoutMs: ownTimeout !== undefined ? ownTimeout : (fallback?.timeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS),
     };
 }
-/** Lower a named engine through the canonical harness platform. */
-export function resolveEngine(name, config) {
-    const engine = resolveEngineConfig(name, config);
-    if (engine.kind === "llm") {
-        const resolved = resolveLlmEngineUse(config, [{ engine: name }]);
-        if (!resolved)
-            throw new ConfigError(`LLM engine "${name}" could not be resolved.`, "LLM_NOT_CONFIGURED");
-        return {
-            kind: "llm",
-            engine: name,
-            connection: resolved.connection,
-            ...(resolved.credential ? { credential: resolved.credential } : {}),
-            ...(resolved.apiKeyFile ? { apiKeyFile: resolved.apiKeyFile } : {}),
-            ...(resolved.apiKeySecretRef ? { apiKeySecretRef: resolved.apiKeySecretRef } : {}),
-            timeoutMs: resolved.timeoutMs,
-        };
-    }
-    return lowerAgentEngine(name, engine, config);
+/** Resolve a configured engine name to its runner: an LLM connection, a spawned agent, or the SDK. */
+export function resolveEngine(name, config, engine = configuredEngine(name, config)) {
+    if (engine.kind !== "llm")
+        return lowerAgentEngine(name, engine, config);
+    const resolved = resolveLlmEngineUse(config, [{ engine: name }]);
+    return {
+        kind: "llm",
+        engine: name,
+        connection: resolved.connection,
+        ...(resolved.credential ? { credential: resolved.credential } : {}),
+        ...(resolved.apiKeyFile ? { apiKeyFile: resolved.apiKeyFile } : {}),
+        ...(resolved.apiKeySecretRef ? { apiKeySecretRef: resolved.apiKeySecretRef } : {}),
+        timeoutMs: resolved.timeoutMs,
+    };
 }