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

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

@@ -28,8 +28,69 @@
  * (X2) can wrap `executeRunner` without changing this contract.
  */
 import { assertNever } from "../../core/assert.js";
-import { runOpencodeSdk } from "../harnesses/opencode-sdk/index.js";
+import { collectSensitiveValues, isEnvPassthroughValueSafeToExpose, redactSensitiveText, redactSensitiveValue, } from "../../core/redaction.js";
+import { closeServer as disposeOpencodeSdkServers, runOpencodeSdk } from "../harnesses/opencode-sdk/sdk-runner.js";
+import { materializeLlmConnection } from "./engine-resolution.js";
+import { materializeLlmRunnerConnection } from "./runner.js";
 import { runAgent } from "./spawn.js";
+/**
+ * Release every long-lived resource the dispatch runners CACHE for reuse, so a
+ * one-shot process (the CLI) can exit cleanly once dispatching is done.
+ *
+ * The `sdk` runner keeps a per-material registry of `opencode serve` CHILD
+ * PROCESSES (see `opencode-sdk/sdk-runner.ts`), started lazily and reused
+ * across units within a process. Each live child is an OS handle that keeps
+ * Bun's event loop open — and the registry's own teardown is wired ONLY to
+ * `process.once('exit')`, which never fires while such a child holds the loop
+ * open. That is a deadlock: a successful `akm workflow run` that dispatched via
+ * the SDK path would hang the CLI (owner finding 4) because the process is
+ * never idle enough for the exit hook to run and close the children it is
+ * waiting on.
+ *
+ * The CLI composition root and workflow engine call this in `finally` blocks to
+ * drain the registry deterministically before relying on the event loop. Started
+ * servers close synchronously; in-flight starts are awaited and closed on
+ * arrival. When no SDK server was started this is an idempotent no-op.
+ */
+export async function disposeDispatchResources() {
+    await disposeOpencodeSdkServers();
+}
+/** Collect every materialized value that can reach one runner dispatch. */
+export function collectDispatchSensitiveValues(spec, opts, envSource = opts.envSource ?? process.env) {
+    const values = new Set();
+    const add = (value) => {
+        if (value !== undefined && value.length > 0)
+            values.add(value);
+    };
+    const addConnection = (connection) => add(connection?.apiKey);
+    if (spec.kind === "llm")
+        addConnection(spec.connection);
+    if (spec.kind === "sdk")
+        addConnection(spec.fallbackConnection);
+    if (spec.kind !== "llm") {
+        for (const value of Object.values(spec.profile.env ?? {}))
+            add(value);
+        for (const name of spec.profile.envPassthrough) {
+            const value = envSource[name];
+            if (!isEnvPassthroughValueSafeToExpose(name, value))
+                add(value);
+        }
+    }
+    for (const [name, value] of Object.entries(opts.env ?? {})) {
+        if (!isEnvPassthroughValueSafeToExpose(name, value))
+            add(value);
+    }
+    return collectSensitiveValues(values);
+}
+function redactResult(result, sensitiveValues) {
+    return {
+        ...result,
+        stdout: redactSensitiveText(result.stdout, sensitiveValues),
+        stderr: redactSensitiveText(result.stderr, sensitiveValues),
+        ...(result.error !== undefined ? { error: redactSensitiveText(result.error, sensitiveValues) } : {}),
+        ...(result.parsed !== undefined ? { parsed: redactSensitiveValue(result.parsed, sensitiveValues) } : {}),
+    };
+}
 /**
  * Dispatch a {@link RunnerSpec} to its runner and return the raw
  * {@link AgentRunResult}. `opts` is the {@link RunAgentOptions} for the profile
@@ -37,23 +98,51 @@ import { runAgent } from "./spawn.js";
  * its exact option set (incl. any `timeoutMs` the caller chose to apply).
  */
 export async function executeRunner(spec, prompt, opts, seams = {}) {
+    const withSpecOptions = (timeoutMs, workspace) => ({
+        ...opts,
+        ...(Object.hasOwn(opts, "timeoutMs") ? {} : timeoutMs !== undefined ? { timeoutMs } : {}),
+        ...(opts.cwd === undefined && workspace ? { cwd: workspace } : {}),
+    });
+    let result;
+    const dispatchSensitiveValues = [];
     switch (spec.kind) {
         case "llm": {
             if (!seams.llm) {
                 throw new Error("executeRunner: an `llm` runner requires a `seams.llm` handler (no default LLM dispatch).");
             }
-            return seams.llm(spec, prompt);
+            const connection = materializeLlmRunnerConnection(spec);
+            if (connection.apiKey)
+                dispatchSensitiveValues.push(connection.apiKey);
+            result = await seams.llm({ ...spec, connection }, prompt, withSpecOptions(spec.timeoutMs));
+            break;
         }
         case "agent": {
             const run = seams.runAgent ?? runAgent;
-            return run(spec.profile, prompt, opts);
+            result = await run(spec.profile, prompt, withSpecOptions(spec.timeoutMs, spec.profile.workspace));
+            break;
         }
         case "sdk": {
             const run = seams.runSdk ?? runOpencodeSdk;
-            return run(spec.profile, prompt, opts);
+            const fallbackConnection = spec.fallbackConnection
+                ? materializeLlmConnection({
+                    engine: spec.engine ?? "unnamed-sdk-fallback",
+                    connection: spec.fallbackConnection,
+                    ...(spec.fallbackCredential ? { credential: spec.fallbackCredential } : {}),
+                    timeoutMs: spec.fallbackTimeoutMs !== undefined
+                        ? spec.fallbackTimeoutMs
+                        : Object.hasOwn(spec.fallbackConnection, "timeoutMs")
+                            ? (spec.fallbackConnection.timeoutMs ?? null)
+                            : null,
+                })
+                : undefined;
+            if (fallbackConnection?.apiKey)
+                dispatchSensitiveValues.push(fallbackConnection.apiKey);
+            result = await run(spec.profile, prompt, withSpecOptions(spec.timeoutMs, spec.profile.workspace), fallbackConnection);
+            break;
         }
         default:
             // Exhaustiveness arm: a 4th RunnerSpec kind becomes a compile error here.
             return assertNever(spec);
     }
+    return redactResult(result, [...collectDispatchSensitiveValues(spec, opts), ...dispatchSensitiveValues]);
 }

package/dist/integrations/agent/runner.js

@@ -2,230 +2,98 @@
 // 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 { warn } from "../../core/warn.js";
-// ── RunnerSpec capability predicates (H1) ───────────────────────────────────
-// The `RunnerSpec` union is dispatched ad-hoc across the improve slice. These
-// predicates co-locate the capability questions with the union definition so
-// callers stop hand-inlining `kind !== "llm"` (which couples the call site to
-// the exact shape of the union). They are typed as TypeScript type guards so
-// narrowing flows through to the `connection` / `profile` accessors.
-/** The in-tree LLM HTTP runner (`chatCompletion`); has no filesystem access. */
+import { materializeLlmConnection, resolveEngine, resolveLlmEngineUse, } from "./engine-resolution.js";
+import { resolveModel } from "./model-aliases.js";
+/** Resolve the current credential value for one frozen LLM runner at dispatch. */
+export function materializeLlmRunnerConnection(runner) {
+    const connectionWithLegacyTimeout = runner.connection;
+    const timeoutMs = runner.timeoutMs !== undefined
+        ? runner.timeoutMs
+        : Object.hasOwn(connectionWithLegacyTimeout, "timeoutMs")
+            ? (connectionWithLegacyTimeout.timeoutMs ?? null)
+            : null;
+    return materializeLlmConnection({
+        engine: runner.engine ?? "unnamed",
+        connection: runner.connection,
+        ...(runner.credential ? { credential: runner.credential } : {}),
+        timeoutMs,
+    });
+}
 export function runnerIsLlm(runner) {
     return runner.kind === "llm";
 }
-/**
- * Whether this runner can honour the file-write contract. Agent CLI + OpenCode
- * SDK runners both have filesystem access; the direct LLM HTTP runner does NOT
- * (see `src/llm/call-ai.ts`). Equivalent to `!runnerIsLlm(runner)` but names
- * the capability the callers actually care about.
- */
 export function runnerSupportsFileWrite(runner) {
     return runner.kind !== "llm";
 }
-function resolveEffectiveMode(entry, profileName, config) {
-    if (entry.mode)
-        return entry.mode;
-    // Infer from profile pool when profile is specified
-    if (profileName) {
-        if (config.profiles?.llm?.[profileName])
-            return "llm";
-        const agentProfile = config.profiles?.agent?.[profileName];
-        if (agentProfile) {
-            return agentProfile.platform === "opencode-sdk" ? "sdk" : "agent";
-        }
-    }
-    // Fall back to defaults
-    if (config.defaults?.llm)
-        return "llm";
-    if (config.defaults?.agent)
-        return "agent";
-    return "llm";
-}
-function resolveProfileName(entry, mode, config) {
-    if (entry.profile)
-        return entry.profile;
-    if (mode === "llm") {
-        const defaultName = config.defaults?.llm;
-        if (defaultName)
-            return defaultName;
-        throw new ConfigError(`No LLM profile configured. Set defaults.llm in config or specify profile in the process entry.`, "LLM_NOT_CONFIGURED", "Run `akm setup` or define a profile under `profiles.llm` and set `defaults.llm`.");
-    }
-    const defaultName = config.defaults?.agent;
-    if (defaultName)
-        return defaultName;
-    throw new ConfigError(`No agent profile configured. Set defaults.agent in config or specify profile in the process entry.`, "INVALID_CONFIG_FILE", "Run `akm setup` to configure an agent profile, or add one under `profiles.agent`.");
-}
-function buildLlmRunnerSpec(profileName, timeoutMs, config) {
-    const profile = config.profiles?.llm?.[profileName];
-    if (!profile) {
-        throw new ConfigError(`LLM profile "${profileName}" not found in profiles.llm.`, "LLM_NOT_CONFIGURED", `Available profiles: ${Object.keys(config.profiles?.llm ?? {}).join(", ") || "none"}. Run \`akm setup\` to configure.`);
-    }
+/** Resolve the configured LLM default without ever consulting retired profiles. */
+export function resolveDefaultLlmRunner(config, timeoutMs) {
+    const resolved = resolveLlmEngineUse(config, [], { optional: true });
+    if (!resolved)
+        return null;
     return {
         kind: "llm",
-        connection: profile,
-        ...(typeof timeoutMs === "number" ? { timeoutMs } : {}),
-    };
-}
-function buildAgentRunnerSpec(kind, profileName, timeoutMs, config) {
-    const profileConfig = config.profiles?.agent?.[profileName];
-    if (!profileConfig) {
-        throw new ConfigError(`Agent profile "${profileName}" not found in profiles.agent.`, "INVALID_CONFIG_FILE", `Available profiles: ${Object.keys(config.profiles?.agent ?? {}).join(", ") || "none"}. Run \`akm setup\` to configure.`);
-    }
-    // Validate mode/platform consistency
-    if (kind === "sdk" && profileConfig.platform !== "opencode-sdk") {
-        throw new ConfigError(`Mode "sdk" requires platform "opencode-sdk", but profiles.agent["${profileName}"].platform is "${profileConfig.platform}".`, "INVALID_CONFIG_FILE");
-    }
-    if (kind === "agent" && profileConfig.platform === "opencode-sdk") {
-        throw new ConfigError(`Mode "agent" requires platform "opencode" or "claude", but profiles.agent["${profileName}"].platform is "opencode-sdk".`, "INVALID_CONFIG_FILE");
-    }
-    const agentProfile = {
-        name: profileName,
-        bin: profileConfig.bin ?? profileName,
-        args: profileConfig.args ?? [],
-        stdio: "captured",
-        envPassthrough: [],
-        parseOutput: "text",
-        ...(profileConfig.model ? { model: profileConfig.model } : {}),
-        ...(profileConfig.workspace ? { workspace: profileConfig.workspace } : {}),
-    };
-    return {
-        kind,
-        profile: agentProfile,
-        ...(typeof timeoutMs === "number" ? { timeoutMs } : {}),
+        engine: resolved.engine,
+        connection: resolved.connection,
+        ...(resolved.credential ? { credential: resolved.credential } : {}),
+        ...(timeoutMs !== undefined ? { timeoutMs } : { timeoutMs: resolved.timeoutMs }),
     };
 }
-/**
- * Resolve the runner used for "validation" passes on the `improve` section
- * (Advantage D3 / Phase 4B — third model tier).
- *
- * Look-up order:
- *   1. `profiles.improve.default.processes.validation` (preferred — lets users
- *      wire a lower-cost classifier model for staleness detection, confidence
- *      scoring, and lesson classification).
- *   2. `defaults.llm` as a final fallback so callers always get a usable
- *      runner when any LLM is configured.
- *
- * Returns `null` when neither is configured (callers may then skip the
- * validation pass rather than throwing).
- */
-/**
- * Shared resolution path for the `validation` and `triage judgment` tiers,
- * both of which take a `{ mode?, profile?, timeoutMs? }`-shaped block, attempt
- * to resolve it via {@link resolveImproveProcessRunnerFromProfile}, and
- * otherwise fall back to an `llm` runner built from `defaults.llm`.
- *
- * @param block          the `{ mode?, profile?, timeoutMs? }` subset to resolve.
- * @param config         the active AKM config.
- * @param opts.fallbackTimeoutMs  timeout applied to the `defaults.llm` fallback
- *        runner (validation passes `undefined`; triage forwards `block.timeoutMs`).
- * @param opts.suppressLlmFallbackForExplicitMode  when `true` and the block
- *        explicitly sets `mode: "agent"` or `"sdk"`, do NOT silently fall back
- *        to `defaults.llm` if the profile resolver returns `null` or throws —
- *        return `null` instead and emit a `warn(...)` (see FIX 8). Validation
- *        passes `false` to preserve its always-fallback behavior.
- */
-function resolveProcessRunnerWithLlmFallback(block, config, opts) {
-    const explicitNonLlmMode = block?.mode === "agent" || block?.mode === "sdk";
-    if (block && (block.mode || block.profile)) {
-        try {
-            const spec = resolveImproveProcessRunnerFromProfile(block, config);
-            if (spec)
-                return spec;
+/** Resolve a triage judgment using judgment -> triage -> strategy -> defaults.llmEngine precedence. */
+export function resolveTriageJudgmentRunner(judgment, config, triage, strategy) {
+    const layers = [strategy ?? {}, triage ?? {}, judgment ?? {}];
+    const selectedEngine = judgment?.engine ?? triage?.engine ?? strategy?.engine ?? config.defaults?.llmEngine;
+    if (selectedEngine) {
+        const runner = resolveEngine(selectedEngine, config);
+        if (runner.kind === "llm") {
+            const resolved = resolveLlmEngineUse(config, layers);
+            return {
+                kind: "llm",
+                engine: resolved.engine,
+                connection: resolved.connection,
+                ...(resolved.credential ? { credential: resolved.credential } : {}),
+                timeoutMs: resolved.timeoutMs,
+            };
         }
-        catch {
-            // Fall through to defaults.llm below (unless suppressed for explicit modes).
-        }
-        // FIX 8: an EXPLICIT agent/sdk request must not be silently downgraded to
-        // llm. When the profile resolver could not produce a runner, surface the
-        // misconfiguration and let callers skip this tier rather than substituting
-        // an llm judge.
-        if (opts.suppressLlmFallbackForExplicitMode && explicitNonLlmMode) {
-            warn(`[akm] Could not resolve the "${block?.mode}" judgment profile; ` +
-                `skipping the judgment tier instead of falling back to an llm judge. ` +
-                `Check profiles.agent and the judgment profile/mode configuration.`);
-            return null;
-        }
-    }
-    const defaultLlm = config.defaults?.llm;
-    if (defaultLlm) {
-        try {
-            return buildLlmRunnerSpec(defaultLlm, opts.fallbackTimeoutMs, config);
-        }
-        catch {
-            return null;
+        const effectiveLlmOverrides = [...layers].reverse().find((layer) => layer.llm !== undefined)?.llm;
+        if (effectiveLlmOverrides) {
+            throw new ConfigError(`Triage judgment engine "${selectedEngine}" is an agent engine and cannot receive llm overrides.`, "INVALID_CONFIG_FILE");
         }
+        const model = [...layers].reverse().find((layer) => layer.model !== undefined)?.model;
+        const profile = model
+            ? {
+                ...runner.profile,
+                model: resolveModel(model, runner.profile.platform ?? runner.profile.name, runner.profile.modelAliases, runner.profile.globalModelAliases),
+                modelIsExact: true,
+            }
+            : runner.profile;
+        const timeoutLayer = [...layers].reverse().find((layer) => Object.hasOwn(layer, "timeoutMs"));
+        return {
+            ...runner,
+            profile,
+            ...(timeoutLayer ? { timeoutMs: timeoutLayer.timeoutMs ?? null } : {}),
+        };
     }
     return null;
 }
-/**
- * Build the tool-less HTTP runner from `defaults.llm`, or `null` when unset.
- * The unattended-improve reflect pin (meta-review 07 Chain-G / P1.3) uses this
- * as the mandatory downgrade target when config would otherwise hand reflect a
- * tool-capable (agent/SDK) runner in a scheduled run. Throws ConfigError when
- * `defaults.llm` names a profile that does not exist.
- */
-export function resolveDefaultLlmRunner(config, timeoutMs) {
-    const name = config.defaults?.llm;
-    if (!name)
-        return null;
-    return buildLlmRunnerSpec(name, timeoutMs, config);
-}
-export function resolveValidationRunner(config) {
-    const validation = config.profiles?.improve?.default?.processes?.validation;
-    const block = validation && validation.enabled !== false ? validation : undefined;
-    return resolveProcessRunnerWithLlmFallback(block, config, {
-        fallbackTimeoutMs: undefined,
-        suppressLlmFallbackForExplicitMode: false,
-    });
+export function resolveImproveProcessLlmUse(config, strategy, processName, options = {}) {
+    const process = strategy?.processes?.[processName];
+    const layers = strategy ? [strategy, process ?? {}] : [];
+    return options.optional
+        ? resolveLlmEngineUse(config, layers, { optional: true })
+        : resolveLlmEngineUse(config, layers);
 }
-/**
- * Resolve the runner for the triage judgment tier (Proposal-Queue Triage,
- * Phase 3). The `judgment` block is a `{ mode?, profile?, timeoutMs? }` subset
- * compatible with {@link ImproveProcessConfig}, so it resolves through the same
- * {@link resolveImproveProcessRunnerFromProfile} path.
- *
- * Mirrors {@link resolveValidationRunner}'s `defaults.llm` fallback only for
- * the unset/`llm` case: when the block sets neither `mode` nor `profile` (so
- * the profile resolver returns `null`) or `mode: "llm"`, fall back to an `llm`
- * runner built from `defaults.llm` so `judgment.mode: llm` defaults are honored
- * (§14). However (FIX 8) when the caller EXPLICITLY sets `mode: "agent"` or
- * `"sdk"` and the profile resolver returns `null` or throws, do NOT downgrade
- * to an llm judge — return `null` (callers skip the judgment tier and emit
- * `triage_deferred`) and emit a `warn(...)`. Returns `null` when nothing is
- * configured.
- */
-export function resolveTriageJudgmentRunner(judgment, config) {
-    return resolveProcessRunnerWithLlmFallback(judgment, config, {
-        fallbackTimeoutMs: judgment?.timeoutMs,
-        suppressLlmFallbackForExplicitMode: true,
-    });
-}
-export function resolveRunner(mode, profileName, config) {
-    if (mode === "llm")
-        return buildLlmRunnerSpec(profileName, undefined, config);
-    return buildAgentRunnerSpec(mode, profileName, undefined, config);
-}
-/**
- * Resolve a RunnerSpec from an improve-profile process entry. Returns `null`
- * when the entry is absent or provides no overrides — callers should fall
- * back to the default per-process runner resolution path.
- */
-export function resolveImproveProcessRunnerFromProfile(processConfig, config) {
-    if (!processConfig)
+/** Resolve the LLM runner selected by an improve strategy and process without reading credentials. */
+export function resolveImproveProcessRunner(strategy, processName, config) {
+    if (!strategy)
         return null;
-    const { mode: explicitMode, profile, timeoutMs } = processConfig;
-    if (!explicitMode && !profile)
+    const resolved = resolveImproveProcessLlmUse(config, strategy, processName, { optional: true });
+    if (!resolved)
         return null;
-    const mode = explicitMode ?? resolveEffectiveMode(processConfig, profile, config);
-    const profileName = profile ?? resolveProfileName(processConfig, mode, config);
-    if (mode === "llm") {
-        return buildLlmRunnerSpec(profileName, timeoutMs, config);
-    }
-    if (mode === "agent" || mode === "sdk") {
-        return buildAgentRunnerSpec(mode, profileName, timeoutMs, config);
-    }
-    return null;
+    return {
+        kind: "llm",
+        engine: resolved.engine,
+        connection: resolved.connection,
+        ...(resolved.credential ? { credential: resolved.credential } : {}),
+        timeoutMs: resolved.timeoutMs,
+    };
 }
-// Re-export `isProcessEnabled` from feature-gate.ts so callers that previously
-// imported it from runner.ts continue to work.
-export { isProcessEnabled } from "../../llm/feature-gate.js";