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

package/dist/commands/health/checks.js

@@ -2,111 +2,226 @@
 // 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 { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
 import { loadConfig } from "../../core/config/config.js";
-import { detectAgentCliProfiles, requireAgentProfile } from "../../integrations/agent/index.js";
-import { TASK_FAIL_RATE_WARN, } from "./types.js";
-const ACTIVE_RUN_WARN_MS = 15 * 60 * 1000;
-/**
- * Probe the configured agent profile. Self-contained (reads config + PATH); the
- * only check that performs IO at dispatch time, preserving the original inline
- * `runAgentProbe()` call site behaviour exactly.
- */
-export function runAgentProbe() {
-    const config = loadConfig();
-    // v2: check profiles.agent first
-    if (config.profiles?.agent) {
-        const defaultName = config.defaults?.agent;
-        const profileCount = Object.keys(config.profiles.agent).length;
-        if (profileCount === 0) {
-            return {
-                name: "agent-profile",
-                kind: "deterministic",
-                status: "unknown",
-                confidence: "high",
-                message: "No agent profiles configured in profiles.agent.",
-            };
-        }
-        const profileName = defaultName ?? Object.keys(config.profiles.agent)[0];
-        const profile = config.profiles.agent[profileName];
+import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
+import { resolveModel } from "../../integrations/agent/model-aliases.js";
+import { resolveImprovePlan } from "../improve/improve-strategies.js";
+import { ACTIVE_RUN_WARN_MS, TASK_FAIL_RATE_WARN, } from "./types.js";
+function credentialAvailable(credential, env) {
+    return !credential?.required || credential.names.some((name) => Boolean(env[name]?.trim()));
+}
+function runConfiguredEngineProbe(checkName, engineName, config, deps) {
+    if (!engineName) {
         return {
-            name: "agent-profile",
+            name: checkName,
             kind: "deterministic",
-            status: "pass",
+            status: "unknown",
             confidence: "high",
-            message: `v2 agent profile "${profileName}" configured (platform: ${profile?.platform ?? "unknown"}).`,
-            evidence: { profile: profileName, platform: profile?.platform, profileCount },
+            message: checkName === "default-llm-engine"
+                ? "No default LLM engine is configured."
+                : "No default engine is configured.",
         };
     }
-    if (!config.profiles?.agent && !config.defaults?.agent) {
+    const env = deps.env ?? process.env;
+    const configuredEngine = config.engines?.[engineName];
+    if (configuredEngine?.kind === "agent" && configuredEngine.platform === "opencode-sdk") {
+        let packageAvailable = false;
+        try {
+            const resolvePackage = deps.resolvePackage ?? ((name) => createRequire(import.meta.url).resolve(name));
+            resolvePackage("@opencode-ai/sdk");
+            packageAvailable = true;
+        }
+        catch {
+            packageAvailable = false;
+        }
+        const binary = configuredEngine.bin ?? "opencode";
+        const version = (deps.spawnSync ?? spawnSync)(binary, ["--version"], { encoding: "utf8", timeout: 5_000 });
+        const binaryAvailable = (version.status ?? 1) === 0;
+        const fallbackEngine = configuredEngine.llmEngine ?? config.defaults?.llmEngine;
+        let fallback;
+        let fallbackCredential;
+        let sdkRunner;
+        const resolve = deps.resolveEngine ?? resolveEngine;
+        try {
+            const resolved = resolve(engineName, config);
+            if (resolved.kind === "sdk")
+                sdkRunner = resolved;
+        }
+        catch {
+            sdkRunner = undefined;
+        }
+        if (sdkRunner?.fallbackConnection) {
+            fallback = { kind: "llm", connection: sdkRunner.fallbackConnection };
+            fallbackCredential = sdkRunner.fallbackCredential;
+        }
+        else if (fallbackEngine) {
+            try {
+                const resolved = resolve(fallbackEngine, config);
+                if (resolved.kind === "llm") {
+                    fallback = resolved;
+                    fallbackCredential = resolved.credential;
+                }
+            }
+            catch {
+                fallback = undefined;
+            }
+        }
+        const configuredModel = configuredEngine.model
+            ? resolveModel(configuredEngine.model, "opencode-sdk", configuredEngine.modelAliases, config.modelAliases)
+            : undefined;
+        const effectiveModel = sdkRunner?.profile.model ?? configuredModel ?? fallback?.connection.model;
+        const fallbackCredentialAvailable = credentialAvailable(fallbackCredential, env);
+        const missing = [
+            !packageAvailable ? "@opencode-ai/sdk package" : undefined,
+            !binaryAvailable ? `${binary} binary` : undefined,
+            fallbackEngine && !fallback ? "configured fallback LLM connection" : undefined,
+            !fallbackCredentialAvailable ? "required fallback credential" : undefined,
+        ].filter((value) => value !== undefined);
         return {
-            name: "agent-profile",
+            name: checkName,
             kind: "deterministic",
-            status: "unknown",
+            status: missing.length === 0 ? "pass" : "warn",
             confidence: "high",
-            message: "No agent config present.",
+            message: missing.length === 0
+                ? `SDK engine "${engineName}" is available.`
+                : `SDK engine "${engineName}" is incomplete: missing ${missing.join(", ")}.`,
+            evidence: {
+                engine: engineName,
+                platform: configuredEngine.platform,
+                runtimeKind: "sdk",
+                binary,
+                binaryAvailable,
+                package: "@opencode-ai/sdk",
+                packageAvailable,
+                model: effectiveModel ?? null,
+                configuredModel: configuredModel ?? null,
+                modelSource: configuredModel ? "sdk" : effectiveModel ? "fallback" : null,
+                fallbackEngine: fallbackEngine ?? null,
+                fallbackEndpoint: fallback?.connection.endpoint ?? null,
+                fallbackModel: fallback?.connection.model ?? null,
+                requiredCredentialAvailable: fallbackCredentialAvailable,
+            },
         };
     }
-    let profile;
     try {
-        profile = requireAgentProfile(config);
-    }
-    catch (error) {
+        const runner = (deps.resolveEngine ?? resolveEngine)(engineName, config);
+        if (runner.kind === "llm") {
+            const requiredCredentialAvailable = credentialAvailable(runner.credential, env);
+            return {
+                name: checkName,
+                kind: "deterministic",
+                status: requiredCredentialAvailable ? "pass" : "warn",
+                confidence: "high",
+                message: requiredCredentialAvailable
+                    ? `LLM engine "${engineName}" is configured.`
+                    : `LLM engine "${engineName}" is configured, but its required credential is unavailable.`,
+                evidence: {
+                    engine: engineName,
+                    platform: null,
+                    runtimeKind: "llm",
+                    model: runner.connection.model,
+                    endpoint: runner.connection.endpoint,
+                    requiredCredentialAvailable,
+                },
+            };
+        }
+        const profile = runner.profile;
+        if (runner.kind === "sdk")
+            throw new Error(`SDK engine "${engineName}" has no matching SDK config.`);
+        const version = (deps.spawnSync ?? spawnSync)(profile.bin, ["--version"], { encoding: "utf8", timeout: 5_000 });
+        if ((version.status ?? 1) !== 0) {
+            return {
+                name: checkName,
+                kind: "deterministic",
+                status: "warn",
+                confidence: "medium",
+                message: `Agent engine "${engineName}" was found but \`--version\` failed.`,
+                evidence: {
+                    engine: engineName,
+                    platform: profile.platform ?? null,
+                    runtimeKind: "agent",
+                    model: profile.model ?? null,
+                },
+            };
+        }
         return {
-            name: "agent-profile",
+            name: checkName,
             kind: "deterministic",
-            status: "warn",
+            status: "pass",
             confidence: "high",
-            message: error instanceof Error ? error.message : String(error),
+            message: `Agent engine "${engineName}" is available.`,
+            evidence: {
+                engine: engineName,
+                platform: profile.platform ?? null,
+                runtimeKind: "agent",
+                model: profile.model ?? null,
+            },
         };
     }
-    if (profile.sdkMode === true) {
+    catch (error) {
         return {
-            name: "agent-profile",
+            name: checkName,
             kind: "deterministic",
-            status: profile.model ? "pass" : "warn",
+            status: "warn",
             confidence: "high",
-            message: profile.model
-                ? `SDK mode profile "${profile.name}" is configured.`
-                : `SDK mode profile "${profile.name}" has no explicit model.`,
-            evidence: { profile: profile.name, sdkMode: true, model: profile.model ?? null },
+            message: error instanceof Error ? error.message : String(error),
         };
     }
-    const detections = detectAgentCliProfiles(config);
-    const detection = detections.find((entry) => entry.name === profile.name);
-    if (!detection?.available) {
+}
+export function runDefaultEngineProbe(deps = {}) {
+    const config = deps.loadConfig?.() ?? loadConfig();
+    return runConfiguredEngineProbe("default-engine", config.defaults?.engine, config, deps);
+}
+export function runDefaultLlmEngineProbe(deps = {}) {
+    const config = deps.loadConfig?.() ?? loadConfig();
+    return runConfiguredEngineProbe("default-llm-engine", config.defaults?.llmEngine, config, deps);
+}
+export function runActiveImproveStrategyProbe(deps = {}) {
+    const config = deps.loadConfig?.() ?? loadConfig();
+    const strategyName = config.defaults?.improveStrategy ?? "default";
+    try {
+        const plan = resolveImprovePlan(strategyName, config);
+        const env = deps.env ?? process.env;
+        const unavailableProcesses = Object.entries(plan.processes).flatMap(([name, process]) => {
+            if (!process.enabled || !process.runner)
+                return [];
+            return credentialAvailable(process.runner.credential, env) ? [] : [name];
+        });
+        if (plan.triageJudgment) {
+            const judgmentCredential = plan.triageJudgment.kind === "llm"
+                ? plan.triageJudgment.credential
+                : plan.triageJudgment.kind === "sdk"
+                    ? plan.triageJudgment.fallbackCredential
+                    : undefined;
+            if (!credentialAvailable(judgmentCredential, env))
+                unavailableProcesses.push("triage.judgment");
+        }
         return {
-            name: "agent-profile",
+            name: "active-improve-strategy",
             kind: "deterministic",
-            status: "fail",
+            status: unavailableProcesses.length === 0 ? "pass" : "warn",
             confidence: "high",
-            message: `Default agent profile "${profile.name}" is not available on PATH.`,
-            evidence: { profile: profile.name, bin: profile.bin },
+            message: unavailableProcesses.length === 0
+                ? `Active improve strategy "${plan.strategy.name}" has available process engines.`
+                : `Active improve strategy "${plan.strategy.name}" has unavailable required credentials for: ${unavailableProcesses.join(", ")}.`,
+            evidence: {
+                strategy: plan.strategy.name,
+                unavailableProcesses,
+            },
         };
     }
-    const version = spawnSync(profile.bin, ["--version"], { encoding: "utf8", timeout: 5_000 });
-    if ((version.status ?? 1) !== 0) {
+    catch (error) {
+        const explicitlyConfigured = config.defaults?.improveStrategy !== undefined || Object.keys(config.improve?.strategies ?? {}).length > 0;
         return {
-            name: "agent-profile",
+            name: "active-improve-strategy",
             kind: "deterministic",
-            status: "warn",
-            confidence: "medium",
-            message: `Agent binary "${profile.bin}" was found but \`--version\` failed.`,
-            evidence: {
-                profile: profile.name,
-                bin: profile.bin,
-                exitCode: version.status ?? null,
-                stderr: (version.stderr ?? "").trim(),
-            },
+            status: explicitlyConfigured ? "warn" : "unknown",
+            confidence: "high",
+            message: `Active improve strategy "${strategyName}" is unavailable: ${error instanceof Error ? error.message : String(error)}`,
+            evidence: { strategy: strategyName, unavailableProcesses: [] },
         };
     }
-    return {
-        name: "agent-profile",
-        kind: "deterministic",
-        status: "pass",
-        confidence: "high",
-        message: `Agent profile "${profile.name}" is available.`,
-        evidence: { profile: profile.name, bin: profile.bin, version: (version.stdout ?? "").trim() },
-    };
 }
 /**
  * The ordered health-check registry. ORDER IS LOAD-BEARING: `akmHealth`
@@ -173,44 +288,89 @@ export const HEALTH_CHECKS = [
     {
         name: "active-runs",
         channel: "hard",
-        run: (ctx) => ({
-            name: "active-runs",
-            kind: "deterministic",
-            status: ctx.stuckActiveRuns === 0 ? "pass" : "warn",
-            confidence: "high",
-            message: ctx.stuckActiveRuns === 0
-                ? "No active task runs exceeded the stale threshold."
-                : `${ctx.stuckActiveRuns} active task run(s) are older than ${Math.round(ACTIVE_RUN_WARN_MS / 60000)} minutes.`,
-            evidence: { stuckActiveRuns: ctx.stuckActiveRuns },
-        }),
+        run: (ctx) => {
+            // Name the stuck task_ids (deduped, oldest first) so an operator knows
+            // WHICH tasks to investigate, not just how many rows are stale. No
+            // pid/liveness detection — that's out of scope here.
+            const named = [...ctx.stuckActiveTasks].sort((a, b) => b.ageMs - a.ageMs);
+            const detail = named.map((t) => `${t.taskId} (${Math.round(t.ageMs / 60000)}m)`).join(", ");
+            return {
+                name: "active-runs",
+                kind: "deterministic",
+                status: ctx.stuckActiveRuns === 0 ? "pass" : "warn",
+                confidence: "high",
+                message: ctx.stuckActiveRuns === 0
+                    ? "No active task runs exceeded the stale threshold."
+                    : `${ctx.stuckActiveRuns} active task run(s) are older than ${Math.round(ACTIVE_RUN_WARN_MS / 60000)} minutes: ${detail}.`,
+                evidence: { stuckActiveRuns: ctx.stuckActiveRuns, stuckActiveTasks: ctx.stuckActiveTasks },
+            };
+        },
+    },
+    {
+        name: "default-engine",
+        channel: "hard",
+        run: () => runDefaultEngineProbe(),
+    },
+    {
+        name: "default-llm-engine",
+        channel: "hard",
+        run: () => runDefaultLlmEngineProbe(),
     },
     {
-        name: "agent-profile",
+        name: "active-improve-strategy",
         channel: "hard",
-        run: () => runAgentProbe(),
+        run: () => runActiveImproveStrategyProbe(),
     },
     {
         // C2 (13-bus-factor): the cron task-failure rate was computed and rendered
         // in the HTML report but never surfaced as an advisory, so a sustained
         // 15–16% fail rate stayed invisible on `akm health`. Warn at/above the SAME
         // 5% threshold the html-report badge uses (see TASK_FAIL_RATE_WARN).
+        //
+        // Item 6: the aggregate can hide a single consistently-failing task inside
+        // a large, mostly-healthy population (e.g. 1 flaky task at 100 rows total
+        // reads as <5% aggregate). Also warn when the single worst task_id (with
+        // enough rows to be a real signal — see MIN_ROWS_FOR_WORST_TASK_FAIL_RATE)
+        // crosses the same threshold, naming it explicitly.
         name: "task-fail-rate",
         channel: "advisory",
         run: (ctx) => {
             const pctStr = `${(ctx.taskFailRate * 100).toFixed(1)}%`;
             const thresholdPct = `${(TASK_FAIL_RATE_WARN * 100).toFixed(0)}%`;
-            const warn = ctx.taskFailRate >= TASK_FAIL_RATE_WARN;
+            const aggregateWarn = ctx.taskFailRate >= TASK_FAIL_RATE_WARN;
+            const worst = ctx.worstTaskFailRate;
+            const worstWarn = worst !== null && worst.rate >= TASK_FAIL_RATE_WARN;
+            const warn = aggregateWarn || worstWarn;
+            let message;
+            if (ctx.taskRowCount === 0) {
+                message = `No cron tasks ran since ${ctx.since} — no task-fail-rate signal.`;
+            }
+            else if (warn) {
+                const parts = [];
+                if (aggregateWarn) {
+                    parts.push(`aggregate ${pctStr} across ${ctx.taskRowCount} task(s) since ${ctx.since} ≥ ${thresholdPct}`);
+                }
+                if (worstWarn && worst) {
+                    const worstPctStr = `${(worst.rate * 100).toFixed(1)}%`;
+                    parts.push(`task "${worst.taskId}" fails ${worstPctStr} of its ${worst.rows} run(s) ≥ ${thresholdPct}`);
+                }
+                message = `Cron task fail rate warning: ${parts.join("; ")} — inspect failed runs (ok=false) for early-exit/harness errors.`;
+            }
+            else {
+                message = `Cron task fail rate ${pctStr} across ${ctx.taskRowCount} task(s) since ${ctx.since} (below ${thresholdPct} threshold).`;
+            }
             return {
                 name: "task-fail-rate",
                 kind: "deterministic",
                 status: warn ? "warn" : "pass",
                 confidence: "high",
-                message: ctx.taskRowCount === 0
-                    ? `No cron tasks ran since ${ctx.since} — no task-fail-rate signal.`
-                    : warn
-                        ? `Cron task fail rate ${pctStr} across ${ctx.taskRowCount} task(s) since ${ctx.since} ≥ ${thresholdPct} threshold — inspect failed runs (ok=false) for early-exit/harness errors.`
-                        : `Cron task fail rate ${pctStr} across ${ctx.taskRowCount} task(s) since ${ctx.since} (below ${thresholdPct} threshold).`,
-                evidence: { taskFailRate: ctx.taskFailRate, taskRowCount: ctx.taskRowCount, threshold: TASK_FAIL_RATE_WARN },
+                message,
+                evidence: {
+                    taskFailRate: ctx.taskFailRate,
+                    taskRowCount: ctx.taskRowCount,
+                    threshold: TASK_FAIL_RATE_WARN,
+                    worstTaskFailRate: worst,
+                },
             };
         },
     },
@@ -228,7 +388,7 @@ export const HEALTH_CHECKS = [
             const endpointAdvisory = blocked && remoteReason && ctx.embeddingEndpoint
                 ? `Configured embedding endpoint ${ctx.embeddingEndpoint} is failing ` +
                     `(${ctx.semanticStatus?.reason}${ctx.semanticStatus?.message ? `: ${ctx.semanticStatus.message}` : ""}) ` +
-                    `while semanticSearchMode is "${ctx.semanticSearchMode ?? "auto"}". Searches fall back to keyword-only. ` +
+                    `while semanticSearchMode is "${ctx.semanticSearchMode ?? "off"}". Searches fall back to keyword-only. ` +
                     `Restore the endpoint, or set semanticSearchMode to "off" (or remove embedding.endpoint to use the local model).`
                 : undefined;
             return {
@@ -363,4 +523,29 @@ export const HEALTH_CHECKS = [
             };
         },
     },
+    {
+        // Item 4: stale durable-transaction journals under $DATA/txn (stranded
+        // recovery state seen twice in a real 0.9 migration) had zero health
+        // visibility. `count`/`unreadable` already exclude journals younger than
+        // the sweeper's grace period (a currently-running operation), so any
+        // nonzero count here is a real leftover.
+        name: "stale-txn-journals",
+        channel: "advisory",
+        run: (ctx) => {
+            const s = ctx.staleTxnJournals;
+            const warn = s.count > 0;
+            const unreadablePart = s.unreadable > 0 ? `, ${s.unreadable} unreadable` : "";
+            const agePart = s.oldestAgeMs !== null ? `, oldest ${Math.round(s.oldestAgeMs / 60000)}m old` : "";
+            return {
+                name: "stale-txn-journals",
+                kind: "deterministic",
+                status: warn ? "warn" : "pass",
+                confidence: "high",
+                message: warn
+                    ? `${s.count} stale transaction journal(s) found under ${s.dir}${unreadablePart}${agePart} — see docs/migration/v0.9.0-troubleshooting.md for journal reconciliation steps.`
+                    : "No stale transaction journals found.",
+                evidence: { dir: s.dir, count: s.count, unreadable: s.unreadable, oldestAgeMs: s.oldestAgeMs },
+            };
+        },
+    },
 ];