akm-cli 0.9.0-rc.0 → 0.9.0-rc.2

package/dist/indexer/search/ranking.js

@@ -3,10 +3,11 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import { makeAssetRef } from "../../core/asset/asset-ref.js";
+import { acquireMaintenanceActivitySync } from "../../core/maintenance-barrier.js";
 import { getStateDbPath } from "../../core/state-db.js";
 import { openDatabase } from "../../storage/database.js";
 import { getUtilityScoresByIds } from "../db/db.js";
-import { applyContributorAblation, applyScoreContributors, applyUtilityContributors, defaultRankingContributors, defaultUtilityRankingContributors, } from "./ranking-contributors.js";
+import { applyBeliefStateScoreCeiling, applyContributorAblation, applyScoreContributors, applyUtilityContributors, defaultRankingContributors, defaultUtilityRankingContributors, } from "./ranking-contributors.js";
 /**
  * R2 — best-effort load of `asset_salience.rank_score` from state.db for the
  * ranked items. Fail-open: any error (state.db locked by a concurrent improve
@@ -27,35 +28,41 @@ export function loadSalienceRankScores(items) {
         const dbPath = getStateDbPath();
         if (!fs.existsSync(dbPath))
             return result; // improve loop has never run here
+        const releaseActivity = acquireMaintenanceActivitySync("state-db");
         const idByRef = new Map();
-        for (const item of items) {
-            idByRef.set(makeAssetRef(item.entry.type, item.entry.name), item.id);
-        }
-        const stateDb = openDatabase(dbPath, { readonly: true });
         try {
-            try {
-                stateDb.exec("PRAGMA busy_timeout = 250");
+            for (const item of items) {
+                idByRef.set(makeAssetRef(item.entry.type, item.entry.name), item.id);
             }
-            catch {
-                // pragma failure on a readonly handle is fine — default timeout applies
-            }
-            const refs = [...idByRef.keys()];
-            const CHUNK = 500;
-            for (let i = 0; i < refs.length; i += CHUNK) {
-                const chunk = refs.slice(i, i + CHUNK);
-                const placeholders = chunk.map(() => "?").join(",");
-                const rows = stateDb
-                    .prepare(`SELECT asset_ref, rank_score FROM asset_salience WHERE asset_ref IN (${placeholders})`)
-                    .all(...chunk);
-                for (const row of rows) {
-                    const id = idByRef.get(row.asset_ref);
-                    if (id !== undefined)
-                        result.set(id, row.rank_score);
+            const stateDb = openDatabase(dbPath, { readonly: true });
+            try {
+                try {
+                    stateDb.exec("PRAGMA busy_timeout = 250");
                 }
+                catch {
+                    // pragma failure on a readonly handle is fine — default timeout applies
+                }
+                const refs = [...idByRef.keys()];
+                const CHUNK = 500;
+                for (let i = 0; i < refs.length; i += CHUNK) {
+                    const chunk = refs.slice(i, i + CHUNK);
+                    const placeholders = chunk.map(() => "?").join(",");
+                    const rows = stateDb
+                        .prepare(`SELECT asset_ref, rank_score FROM asset_salience WHERE asset_ref IN (${placeholders})`)
+                        .all(...chunk);
+                    for (const row of rows) {
+                        const id = idByRef.get(row.asset_ref);
+                        if (id !== undefined)
+                            result.set(id, row.rank_score);
+                    }
+                }
+            }
+            finally {
+                stateDb.close();
             }
         }
         finally {
-            stateDb.close();
+            releaseActivity();
         }
     }
     catch {
@@ -152,6 +159,12 @@ export function applyRankingRules(options) {
     };
     for (const item of options.items) {
         applyUtilityContributors(item, utilityContext, activeUtilityContributors);
+        // SPEC-5: demoting belief states (superseded/contradicted/archived/
+        // deprecated) cap the FINAL score. The additive belief penalty inside the
+        // multiplicative boost sum cannot overcome the FTS min-max normalization
+        // spread, so without the ceiling a superseded incumbent that is the best
+        // keyword match outranks its own correction forever.
+        applyBeliefStateScoreCeiling(item);
     }
     return options.items;
 }

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

@@ -9,7 +9,8 @@
  *  - description: entry description
  *  - tags: tags + aliases joined
  *  - hints: searchHints + examples + usage + intent fields
- *  - content: TOC headings (lowest-weight catch-all)
+ *  - content: TOC headings + parameters + the config-gated body opening
+ *    (lowest-weight catch-all)
  */
 // NOTE (R5): the collapse detector's frozen canary queries are built from the
 // same surface this function indexes (name tokens / tags / description) and
@@ -59,6 +60,15 @@ export function buildSearchFields(entry) {
                 contentParts.push(param.description);
         }
     }
+    // Stash-organization conventions (SPEC-8): the self-situating body opening
+    // (captured by the metadata pass only when `index.indexBodyOpening` is on)
+    // folds into the lowest-weight catch-all column — never name/description/
+    // tags/hints — so orientation prose is retrievable without outranking
+    // structured-field matches. The fold is unconditional on the entry field:
+    // `rebuildFts` rebuilds FTS rows from stored entry_json and must reproduce
+    // the same fields without re-reading config.
+    if (entry.bodyOpening)
+        contentParts.push(entry.bodyOpening);
     const content = contentParts.join(" ").toLowerCase();
     return { name, description, tags, hints, content };
 }

package/dist/indexer/walk/matchers.js

@@ -11,6 +11,8 @@
 import { defaultRendererRegistry } from "../../core/asset/asset-registry.js";
 import { SCRIPT_EXTENSIONS } from "../../core/asset/asset-spec.js";
 import { looksLikeWorkflow } from "../../workflows/parser.js";
+import { looksLikeWorkflowProgram } from "../../workflows/program/parser.js";
+import { WORKFLOW_PROGRAM_RENDERER_NAME } from "../../workflows/program/project.js";
 import { registerMatcher } from "./file-context.js";
 // ---------------------------------------------------------------------------
 // Private data
@@ -178,6 +180,35 @@ function classifyBySmartMd(ctx) {
     }
     return { type: "knowledge", specificity: 5 };
 }
+/** YAML workflow *programs* (redesign addendum, R1): `.yaml`/`.yml` files. */
+const WORKFLOW_PROGRAM_EXTENSIONS = new Set([".yaml", ".yml"]);
+/**
+ * Classify YAML workflow programs. Two claims, mirroring the markdown rules:
+ *
+ *   - any `.yaml`/`.yml` under a `workflows/` dir (the directory rule —
+ *     specificity 15 when `workflows` is the immediate parent, 10 for a
+ *     deeper ancestor, same ladder as `matchDirectoryHint`);
+ *   - anywhere else, a content probe via `looksLikeWorkflowProgram`
+ *     (`version: 1` + `steps:` at column 0) at specificity 19, the same
+ *     level as `classifyBySmartMd`'s `looksLikeWorkflow` claim.
+ *
+ * The fact does NOT go through `toMatchResult` — the workflow TYPE maps to
+ * the markdown renderer by default, so this classifier names the
+ * `workflow-program-yaml` renderer on its result directly.
+ */
+function classifyByWorkflowProgram(ctx) {
+    if (!WORKFLOW_PROGRAM_EXTENSIONS.has(ctx.ext))
+        return null;
+    if (isTypedDirDocFile(ctx.fileName))
+        return null;
+    if (ctx.parentDir === "workflows")
+        return { type: "workflow", specificity: 15 };
+    if (ctx.ancestorDirs.includes("workflows"))
+        return { type: "workflow", specificity: 10 };
+    if (looksLikeWorkflowProgram(ctx.content()))
+        return { type: "workflow", specificity: 19 };
+    return null;
+}
 function classifyByWiki(ctx) {
     if (ctx.ext !== ".md")
         return null;
@@ -223,12 +254,20 @@ export function smartMdMatcher(ctx) {
 export function wikiMatcher(ctx) {
     return toMatchResult(ctx, classifyByWiki);
 }
+export function workflowProgramMatcher(ctx) {
+    const fact = classifyByWorkflowProgram(ctx);
+    if (!fact)
+        return null;
+    // Named directly (not via rendererNameFor) — see classifyByWorkflowProgram.
+    return { type: fact.type, specificity: fact.specificity, renderer: WORKFLOW_PROGRAM_RENDERER_NAME };
+}
 const builtinMatchers = [
     extensionMatcher,
     directoryMatcher,
     parentDirHintMatcher,
     smartMdMatcher,
     wikiMatcher,
+    workflowProgramMatcher,
 ];
 export function registerBuiltinMatchers() {
     for (const matcher of builtinMatchers) {

package/dist/integrations/agent/builder-shared.js

@@ -14,6 +14,13 @@
  * their previous home in `builders.ts`.
  */
 import { UsageError } from "../../core/errors.js";
+import { resolveModel } from "./model-aliases.js";
+/** Resolve a raw dispatch model once, while preserving frozen/lowered models verbatim. */
+export function resolveDispatchModel(request, profile, platform) {
+    if (!request.model || request.modelIsExact)
+        return request.model;
+    return resolveModel(request.model, platform, profile.modelAliases, profile.globalModelAliases);
+}
 /**
  * Guard against values that start with `--`, which would be mis-interpreted as
  * CLI flags by the spawned process when used as flag values (model, systemPrompt).

package/dist/integrations/agent/builders.js

@@ -14,50 +14,17 @@
  */
 import { ConfigError } from "../../core/errors.js";
 import { HARNESS_REGISTRY } from "../harnesses/index.js";
-// Types + shared validation helpers live in the leaf module `builder-shared.ts`
-// so per-harness builders (harnesses/claude/agent-builder.ts) can depend on them
-// without importing this file back — avoiding an init-order cycle through
-// BUILTIN_BUILDERS (#563). Re-exported here so existing `agent/builders` import
-// sites keep working.
-import { assertNotFlag } from "./builder-shared.js";
-import { resolveModel } from "./model-aliases.js";
-import { getBuiltinAgentProfile } from "./profiles.js";
 export { assertNotFlag, normalizeTools } from "./builder-shared.js";
 // ── Platform builders ─────────────────────────────────────────────────────────
 // The OpenCode builder was migrated to its harness directory in #564
 // (`harnesses/opencode/agent-builder.ts`) and the Claude Code builder in #563
 // (`harnesses/claude/agent-builder.ts`). Both are imported back into
 // BUILTIN_BUILDERS below so platform routing is unchanged.
-/**
- * Default builder — used for custom profiles and any platform without a
- * dedicated builder. Passes systemPrompt and model via the same flags as
- * the builtin builders so custom profiles benefit from agent asset metadata.
- * Tools are omitted — no standard cross-platform flag exists.
- */
-const defaultBuilder = {
-    platform: "default",
-    build(profile, req) {
-        assertNotFlag(req.systemPrompt, "systemPrompt");
-        assertNotFlag(req.model, "model");
-        const args = [...profile.args];
-        if (req.systemPrompt) {
-            args.push("--system-prompt", req.systemPrompt);
-        }
-        if (req.model) {
-            const resolved = resolveModel(req.model, profile.name, profile.modelAliases, profile.globalModelAliases);
-            args.push("--model", resolved);
-        }
-        args.push("--");
-        args.push(req.prompt);
-        return { argv: [profile.bin, ...args] };
-    },
-};
 // ── Registry ──────────────────────────────────────────────────────────────────
 /**
  * DERIVED from `HARNESS_REGISTRY` (P0.5 registry-drift fix): each harness that
- * owns an `agentBuilder` is registered under its canonical id, its
- * `<id>-headless` profile variant, and every alias. Previously this was a
- * hand-maintained map that could (and did) drift from the harness registry.
+ * owns an `agentBuilder` is registered under its canonical id. Named engines
+ * are schema-validated to canonical harness ids before reaching this boundary.
  */
 const BUILTIN_BUILDERS = (() => {
     const registry = {};
@@ -65,30 +32,18 @@ const BUILTIN_BUILDERS = (() => {
         if (!harness.agentBuilder)
             continue;
         registry[harness.id] = harness.agentBuilder;
-        registry[`${harness.id}-headless`] = harness.agentBuilder;
-        for (const alias of harness.aliases)
-            registry[alias] = harness.agentBuilder;
     }
     return Object.freeze(registry);
 })();
 /**
  * Return the builder for the given platform name.
  *
- * A *custom* profile (unknown platform) falls back to the default builder —
- * that generic `--system-prompt`/`--model`/`--` shape is the documented
- * contract for user-defined wrappers. A *known built-in agent CLI* with no
- * dedicated builder (codex, gemini, aider + their `-headless` variants) is a
- * loud `ConfigError` instead: the default flag shape is wrong for those CLIs
- * (aider, for one, treats positionals as file names), so the old silent
- * fallback produced a broken command that "ran" and failed downstream.
- * Custom builders injected via tests can be passed as `registry`.
+ * Unknown platforms are rejected: there is no safe generic CLI flag shape.
+ * Custom builders injected by tests can be passed as `registry`.
  */
 export function getCommandBuilder(platform, registry = BUILTIN_BUILDERS) {
     const found = registry[platform];
     if (found)
         return found;
-    if (getBuiltinAgentProfile(platform)) {
-        throw new ConfigError(`agent dispatch for "${platform}" is not supported yet: no command builder exists for this CLI, and the generic flag shape would produce a broken command.`, "INVALID_CONFIG_FILE", 'Use an "opencode" or "claude" profile, or — if your CLI is flag-compatible with one of those — set `profiles.agent.<name>.commandBuilder` to "opencode" or "claude".');
-    }
-    return defaultBuilder;
+    throw new ConfigError(`Agent platform "${platform}" has no registered command builder.`, "INVALID_CONFIG_FILE", "Select a canonical agent platform in engines.<name>.platform.");
 }

package/dist/integrations/agent/config.js

@@ -1,147 +1,7 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { ConfigError } from "../../core/errors.js";
-import { BUILTIN_AGENT_PROFILE_NAMES, getBuiltinAgentProfile, listBuiltinAgentProfiles, } from "./profiles.js";
-/**
- * Default hard timeout for an agent CLI (60s — matches the value used in
- * `docs/configuration.md`).
- */
+/** Default hard timeout for an agent CLI when neither engine nor call overrides it. */
 export const DEFAULT_AGENT_TIMEOUT_MS = 60_000;
-/**
- * Resolve the effective `AgentProfile` for `name` by merging the optional
- * user override (`profiles.agent[name]`) on top of the built-in profile (if
- * any). Returns `undefined` when neither yields a usable profile.
- */
-export function resolveAgentProfile(name, overrides, globalModelAliases) {
-    const builtin = getBuiltinAgentProfile(name);
-    const platform = overrides?.platform;
-    // For opencode-sdk profiles, allow synthesizing without a built-in.
-    const sdkMode = platform === "opencode-sdk";
-    if (!builtin && !overrides?.bin && !sdkMode)
-        return undefined;
-    const base = builtin ??
-        {
-            name,
-            bin: overrides?.bin ?? name,
-            args: [],
-            stdio: "captured",
-            envPassthrough: [],
-            parseOutput: "text",
-            ...(sdkMode ? { sdkMode: true } : {}),
-        };
-    if (!overrides) {
-        return globalModelAliases ? { ...base, globalModelAliases } : base;
-    }
-    // Per-profile aliases from config extend (and shadow) the built-in
-    // profile's own entries. (Previously always used base.modelAliases, so the
-    // documented `profiles.agent.<name>.modelAliases` config was silently
-    // dropped — same bug class as the timeoutMs override below.)
-    const modelAliases = overrides.modelAliases || base.modelAliases ? { ...base.modelAliases, ...overrides.modelAliases } : undefined;
-    return {
-        name,
-        bin: overrides.bin ?? base.bin,
-        args: overrides.args ?? base.args,
-        stdio: base.stdio,
-        env: base.env,
-        envPassthrough: base.envPassthrough,
-        // Honor a user-configured `profiles.agent.<name>.timeoutMs` override; fall
-        // back to the built-in profile's value. (Previously always used base, so
-        // the documented config override was silently ignored — callers had to pass
-        // a CLI flag like `--timeout-ms`.) runAgent (spawn.ts) reads profile.timeoutMs
-        // when no per-call timeout is supplied, so this makes the config knob work.
-        timeoutMs: overrides.timeoutMs ?? base.timeoutMs,
-        parseOutput: base.parseOutput,
-        ...(sdkMode ? { sdkMode: true } : {}),
-        model: overrides.model ?? base.model,
-        endpoint: base.endpoint,
-        apiKey: base.apiKey,
-        commandBuilder: base.commandBuilder,
-        modelAliases,
-        ...(globalModelAliases ? { globalModelAliases } : {}),
-    };
-}
-/**
- * Resolve the runnable profile for `name`, or `undefined` if none is
- * available (no built-in and no user override). Threads the config-root
- * `modelAliases` tier table onto the resolved profile.
- */
-export function resolveProfileFromConfig(name, config) {
-    return resolveAgentProfile(name, config?.profiles?.agent?.[name], config?.modelAliases);
-}
-/**
- * Return the names of every agent profile available in `config` — built-ins
- * plus any user-defined entries under `profiles.agent`. Sorted, deduplicated.
- */
-export function listAgentProfileNames(config) {
-    const seen = new Set(BUILTIN_AGENT_PROFILE_NAMES);
-    for (const name of Object.keys(config?.profiles?.agent ?? {}))
-        seen.add(name);
-    return [...seen].sort();
-}
-/**
- * Resolve the default agent profile name. Order: explicit `requested` arg →
- * `config.defaults.agent` → undefined.
- */
-export function resolveDefaultProfileName(config, requested) {
-    if (requested?.trim())
-        return requested.trim();
-    const def = config?.defaults?.agent;
-    if (typeof def === "string" && def.trim())
-        return def.trim();
-    return undefined;
-}
-/**
- * Throw a stable `ConfigError` when the caller needs an agent profile but
- * none can be resolved.
- */
-export function requireAgentProfile(config, requested) {
-    if (!config) {
-        throw new ConfigError("agent commands are disabled: no agent configuration in config.json.", "INVALID_CONFIG_FILE", "Run `akm setup` to detect and configure an agent CLI, or add an entry under `profiles.agent` and set `defaults.agent`.");
-    }
-    const name = resolveDefaultProfileName(config, requested);
-    if (!name) {
-        throw new ConfigError("agent commands require a profile: pass --profile or set `defaults.agent` in config.json.", "INVALID_CONFIG_FILE", `Available profiles: ${listAgentProfileNames(config).join(", ")}.`);
-    }
-    const profile = resolveProfileFromConfig(name, config);
-    if (!profile) {
-        throw new ConfigError(`agent profile "${name}" is not built-in and has no \`bin\` override.`, "INVALID_CONFIG_FILE", `Define profiles.agent."${name}".bin in config.json, or pick one of: ${listAgentProfileNames(config).join(", ")}.`);
-    }
-    return profile;
-}
-/**
- * Resolve the agent profile bound to a named improve process. Reads from
- * `profiles.improve.default.processes.<processName>` for the profile binding,
- * then falls back to `defaults.agent`.
- */
-export function resolveProcessAgentProfile(processName, config) {
-    const processEntry = config?.profiles?.improve?.default?.processes;
-    const entry = processEntry?.[processName];
-    const profileName = entry?.profile;
-    const profile = requireAgentProfile(config, profileName);
-    let resolvedTimeoutMs;
-    if (entry?.timeoutMs === null) {
-        resolvedTimeoutMs = null;
-    }
-    else if (typeof entry?.timeoutMs === "number") {
-        resolvedTimeoutMs = entry.timeoutMs;
-    }
-    else if (profile.timeoutMs !== undefined) {
-        resolvedTimeoutMs = profile.timeoutMs;
-    }
-    return { profile, timeoutMs: resolvedTimeoutMs };
-}
-/**
- * Convenience: list every fully-resolved profile (built-ins merged with
- * user overrides). Used by setup detection to enumerate candidates.
- */
-export function listResolvedAgentProfiles(config) {
-    const resolved = [];
-    const builtins = listBuiltinAgentProfiles();
-    for (const name of listAgentProfileNames(config)) {
-        const profile = resolveProfileFromConfig(name, config) ?? builtins[name];
-        if (profile)
-            resolved.push(profile);
-    }
-    return resolved;
-}
+/** Default hard timeout for direct LLM calls when no engine/use override exists. */
+export const DEFAULT_LLM_TIMEOUT_MS = 600_000;

package/dist/integrations/agent/detect.js

@@ -15,7 +15,7 @@
  */
 import fs from "node:fs";
 import path from "node:path";
-import { listResolvedAgentProfiles } from "./config.js";
+import { getBuiltinAgentProfile, listBuiltinAgentProfiles } from "./profiles.js";
 /**
  * Default PATH lookup. Walks `process.env.PATH` and returns the first
  * existing executable file. Returns `undefined` when the bin is not on
@@ -71,7 +71,22 @@ export function _setAgentDetectForTests(fakes) {
 export function detectAgentCliProfiles(agent, whichFn = defaultWhich) {
     if (detectOverrides?.detectAgentCliProfiles)
         return detectOverrides.detectAgentCliProfiles(agent, whichFn);
-    const profiles = listResolvedAgentProfiles(agent);
+    const profilesByName = new Map(Object.values(listBuiltinAgentProfiles()).map((profile) => [profile.name, profile]));
+    for (const [name, engine] of Object.entries(agent?.engines ?? {})) {
+        if (engine.kind !== "agent")
+            continue;
+        const builtin = getBuiltinAgentProfile(engine.platform);
+        profilesByName.set(name, {
+            name,
+            platform: engine.platform,
+            bin: engine.bin ?? builtin?.bin ?? (engine.platform === "opencode-sdk" ? "opencode" : engine.platform),
+            args: engine.args ?? builtin?.args ?? [],
+            stdio: "captured",
+            envPassthrough: builtin?.envPassthrough ?? [],
+            parseOutput: "text",
+        });
+    }
+    const profiles = [...profilesByName.values()];
     return profiles.map((profile) => probeProfile(profile, whichFn));
 }
 function probeProfile(profile, whichFn) {

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

@@ -0,0 +1,202 @@
+// 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 path from "node:path";
+import { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { ConfigError } from "../../core/errors.js";
+import { formatExtraParamsIssue, validateExtraParams } from "../../core/extra-params.js";
+import { collectSensitiveValues } from "../../core/redaction.js";
+import { getHarness } from "../harnesses/index.js";
+import { DEFAULT_AGENT_TIMEOUT_MS, DEFAULT_LLM_TIMEOUT_MS } from "./config.js";
+import { resolveLlmModel, resolveModel } from "./model-aliases.js";
+import { getBuiltinAgentProfile } from "./profiles.js";
+function hasOwn(value, key) {
+    return Object.hasOwn(value, key);
+}
+function envName(reference) {
+    const match = /^\$(?:\{)?([A-Za-z_][A-Za-z0-9_]*)(?:\})?$/.exec(reference);
+    return match?.[1];
+}
+function selectedEngineName(config, layers, llmOnly) {
+    for (let index = layers.length - 1; index >= 0; index--) {
+        if (layers[index]?.engine !== undefined)
+            return layers[index]?.engine;
+    }
+    return llmOnly ? config.defaults?.llmEngine : config.defaults?.engine;
+}
+function resolveEngineConfig(name, config) {
+    const engine = config.engines?.[name];
+    if (!engine) {
+        throw new ConfigError(`Engine "${name}" is not configured.`, "INVALID_CONFIG_FILE");
+    }
+    return engine;
+}
+function resolveCredential(name, engine, config) {
+    if (engine.apiKey !== undefined) {
+        const explicit = envName(engine.apiKey);
+        if (!explicit)
+            throw new ConfigError(`Engine "${name}" has an invalid symbolic apiKey reference.`, "INVALID_CONFIG_FILE");
+        return { names: [explicit], required: true };
+    }
+    const specific = `AKM_ENGINE_${name.toUpperCase().replaceAll("-", "_")}_API_KEY`;
+    return config.defaults?.llmEngine === name
+        ? { names: [specific, "AKM_LLM_API_KEY"], required: false }
+        : { names: [specific], required: false };
+}
+/** Collect materialized engine credentials for output and persistence redaction. */
+export function collectEngineCredentialValues(config, envSource = process.env) {
+    const values = new Set();
+    for (const [name, engine] of Object.entries(config.engines ?? {})) {
+        if (engine.kind !== "llm")
+            continue;
+        for (const envVar of resolveCredential(name, engine, config)?.names ?? []) {
+            const value = envSource[envVar]?.trim();
+            if (value)
+                values.add(value);
+        }
+    }
+    return collectSensitiveValues(values);
+}
+function effectiveTimeout(engine, layers, fallback) {
+    for (let index = layers.length - 1; index >= 0; index--) {
+        if (hasOwn(layers[index] ?? {}, "timeoutMs"))
+            return layers[index]?.timeoutMs ?? null;
+    }
+    return hasOwn(engine, "timeoutMs") ? (engine.timeoutMs ?? null) : fallback;
+}
+export function resolveLlmEngineUse(config, layers, options = {}) {
+    const name = selectedEngineName(config, layers, true);
+    if (!name) {
+        if (options.optional)
+            return undefined;
+        throw new ConfigError("No LLM engine is selected. Set defaults.llmEngine or specify engine.", "LLM_NOT_CONFIGURED");
+    }
+    const engine = resolveEngineConfig(name, config);
+    if (engine.kind !== "llm") {
+        throw new ConfigError(`Engine "${name}" is not an LLM engine.`, "INVALID_CONFIG_FILE");
+    }
+    let connection = {
+        provider: engine.provider,
+        endpoint: engine.endpoint,
+        model: engine.model,
+        temperature: engine.temperature,
+        maxTokens: engine.maxTokens,
+        supportsJsonSchema: engine.supportsJsonSchema,
+        extraParams: engine.extraParams,
+        contextLength: engine.contextLength,
+        enableThinking: engine.enableThinking,
+    };
+    for (const layer of layers) {
+        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];
+    }
+    connection.model = resolveLlmModel(connection.model, name, config.modelAliases);
+    return {
+        engine: name,
+        connection: connection,
+        credential: resolveCredential(name, engine, config),
+        timeoutMs: effectiveTimeout(engine, layers, DEFAULT_LLM_TIMEOUT_MS),
+    };
+}
+/** Read a resolved symbolic credential only at the runtime dispatch boundary. */
+export function materializeLlmConnection(resolved) {
+    if (resolved.connection.extraParams !== undefined) {
+        const issue = validateExtraParams(resolved.connection.extraParams)[0];
+        if (issue) {
+            throw new ConfigError(formatExtraParamsIssue(`Engine "${resolved.engine}" extraParams`, issue), "INVALID_CONFIG_FILE");
+        }
+    }
+    let apiKey;
+    for (const name of resolved.credential?.names ?? []) {
+        const candidate = process.env[name]?.trim();
+        if (candidate) {
+            apiKey = candidate;
+            break;
+        }
+    }
+    if (resolved.credential?.required && !apiKey) {
+        throw new ConfigError(`Required engine credential ${resolved.credential.names[0]} is not set.`, "INVALID_CONFIG_FILE");
+    }
+    return {
+        ...resolved.connection,
+        ...(apiKey ? { apiKey } : {}),
+        timeoutMs: resolved.timeoutMs,
+    };
+}
+function lowerAgentEngine(name, engine, config) {
+    const harness = getHarness(engine.platform);
+    if (!harness?.capabilities.agentDispatch) {
+        throw new ConfigError(`Engine "${name}" names a platform that cannot dispatch agents: ${engine.platform}.`, "INVALID_CONFIG_FILE");
+    }
+    const platform = harness.id;
+    const sdk = platform === "opencode-sdk";
+    const builtin = getBuiltinAgentProfile(platform);
+    const profile = {
+        name,
+        platform,
+        bin: engine.bin ?? builtin?.bin ?? (sdk ? "opencode" : platform),
+        args: engine.args ?? builtin?.args ?? [],
+        stdio: "captured",
+        ...(builtin?.env ? { env: builtin.env } : {}),
+        envPassthrough: builtin?.envPassthrough ?? [],
+        parseOutput: "text",
+        ...(engine.workspace ? { workspace: path.resolve(engine.workspace) } : {}),
+        ...(engine.model
+            ? {
+                model: resolveModel(engine.model, platform, engine.modelAliases, config.modelAliases),
+                modelIsExact: true,
+            }
+            : {}),
+        ...(engine.modelAliases ? { modelAliases: engine.modelAliases } : {}),
+        ...(config.modelAliases ? { globalModelAliases: config.modelAliases } : {}),
+    };
+    if (!sdk) {
+        return {
+            kind: "agent",
+            engine: name,
+            profile,
+            timeoutMs: hasOwn(engine, "timeoutMs") ? (engine.timeoutMs ?? null) : DEFAULT_AGENT_TIMEOUT_MS,
+        };
+    }
+    const fallback = resolveLlmEngineUse(config, [{ engine: engine.llmEngine ?? config.defaults?.llmEngine }]);
+    if (!fallback)
+        throw new ConfigError(`SDK engine "${name}" has no fallback LLM engine.`, "LLM_NOT_CONFIGURED");
+    return {
+        kind: "sdk",
+        engine: name,
+        profile,
+        fallbackConnection: fallback.connection,
+        ...(fallback.credential ? { fallbackCredential: fallback.credential } : {}),
+        fallbackTimeoutMs: fallback.timeoutMs,
+        timeoutMs: hasOwn(engine, "timeoutMs") ? (engine.timeoutMs ?? null) : fallback.timeoutMs,
+    };
+}
+/** 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 } : {}),
+            timeoutMs: resolved.timeoutMs,
+        };
+    }
+    return lowerAgentEngine(name, engine, config);
+}
+export function resolveDefaultEngine(config) {
+    const name = config.defaults?.engine;
+    if (!name)
+        throw new ConfigError("No default engine is configured.", "INVALID_CONFIG_FILE");
+    return resolveEngine(name, config);
+}