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

package/dist/commands/improve/improve-cli.js

@@ -8,16 +8,24 @@ import { output, runWithJsonErrors } from "../../cli/shared.js";
 import { loadConfig } from "../../core/config/config.js";
 import { UsageError } from "../../core/errors.js";
 import { getCacheDir } from "../../core/paths.js";
+import { redactSensitiveText } from "../../core/redaction.js";
 import { withStateDb } from "../../core/state-db.js";
 import { clearLogFile, setLogFile } from "../../core/warn.js";
 import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
 import { resolveSourceEntries } from "../../indexer/search/search-source.js";
+import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
 import { parseFlagValue } from "../../output/context.js";
 import { getActiveCanaries, queryRecentCycleMetrics } from "../../storage/repositories/canaries-repository.js";
 import { refreshCanarySet } from "./collapse-detector.js";
 import { akmImprove } from "./improve.js";
 import { buildImproveRunId, recordTerminatedImproveRun, relativeImproveResultPath, writeImproveResultFile, } from "./improve-result-file.js";
 import { runImproveSession } from "./improve-session.js";
+import { resolveImprovePlan } from "./improve-strategies.js";
+let akmImproveForRun = akmImprove;
+/** Swap the CLI's improve work implementation in deterministic subprocess tests. */
+export function _setAkmImproveForTests(fake) {
+    akmImproveForRun = fake ?? akmImprove;
+}
 // R5 — collapse-detector canary set inspection / explicit refresh. The
 // detector NEVER auto-refreshes the canary set (silent re-baselining is how a
 // slow collapse hides); this verb is the only refresh path.
@@ -72,7 +80,7 @@ async function runCanaryInspection(refresh) {
 export const improveCommand = defineCommand({
     meta: {
         name: "improve",
-        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when profiles.improve.default.processes.consolidate.enabled is true. `akm improve canary [--refresh]` inspects the collapse-detector canary set.",
+        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when the selected strategy enables consolidate. `akm improve canary [--refresh]` inspects the collapse-detector canary set.",
     },
     args: {
         scope: {
@@ -120,9 +128,9 @@ export const improveCommand = defineCommand({
             description: "If another improve run already holds the lock, skip gracefully (exit 0) instead of failing with 'already running' (exit 78). Use for high-frequency scheduled runs so they don't pile up failures while a longer run is in progress.",
             default: false,
         },
-        profile: {
+        strategy: {
             type: "string",
-            description: "Named improve profile from profiles.improve or built-in profiles (default, quick, thorough, memory-focus, graph-refresh). Controls which sub-processes run and which asset types are processed.",
+            description: "Named improve strategy from improve.strategies or built-in strategies (default, quick, thorough, memory-focus, graph-refresh). Controls which sub-processes run and which asset types are processed.",
         },
         sync: {
             type: "boolean",
@@ -166,7 +174,13 @@ export const improveCommand = defineCommand({
             const minRetrievalCount = parseNonNegativeIntFlag(minRetrievalCountRaw, "--min-retrieval-count");
             const requireFeedbackSignal = args["require-feedback-signal"];
             const skipIfLocked = args["skip-if-locked"];
-            const profileArg = getStringArg(args, "profile");
+            const strategyArg = getStringArg(args, "strategy");
+            const effectiveConfig = loadConfig();
+            // Resolve every enabled model-backed process before logging, signal
+            // lifecycle setup, or any filesystem/database side effect.
+            const resolvedPlan = resolveImprovePlan(strategyArg, effectiveConfig);
+            const selectedStrategyName = resolvedPlan.strategy.name;
+            const sensitiveValues = collectEngineCredentialValues(effectiveConfig);
             // Only set the keys the user actually passed (citty leaves the flag
             // undefined unless `--sync`/`--no-sync` / `--push`/`--no-push` appears),
             // so the resolved profile `sync` block wins by default.
@@ -177,8 +191,10 @@ export const improveCommand = defineCommand({
                 syncOverride.enabled = syncFlag;
             if (pushFlag !== undefined)
                 syncOverride.push = pushFlag;
-            const improveLogFile = path.join(getCacheDir(), "logs", "improve", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
-            setLogFile(improveLogFile);
+            if (!dryRun) {
+                const improveLogFile = path.join(getCacheDir(), "logs", "improve", `${new Date().toISOString().replace(/[:.]/g, "-")}.log`);
+                setLogFile(improveLogFile);
+            }
             const startedAtMs = Date.now();
             const startedAtIso = new Date(startedAtMs).toISOString();
             // Mint the run-id up front so signal handlers can persist a partial
@@ -186,7 +202,7 @@ export const improveCommand = defineCommand({
             // was minted at end-of-run, so SIGTERM'd runs (cron timeout) left no
             // row in improve_runs and effectively disappeared from `akm health`.
             const runId = buildImproveRunId();
-            const primaryStashDir = resolveSourceEntries(undefined, loadConfig())[0]?.path;
+            const primaryStashDir = resolveSourceEntries(undefined, effectiveConfig)[0]?.path;
             const scopeArg = getStringArg(args, "scope");
             const inferredScopeMode = (scopeArg ?? "").includes(":") ? "ref" : scopeArg ? "type" : "all";
             // Signal handler + exception path both flow through this helper so
@@ -194,6 +210,8 @@ export const improveCommand = defineCommand({
             // reason in metadata.terminated.
             let runRecorded = false;
             const persistTerminated = (reason, errorMessage) => {
+                if (dryRun)
+                    return;
                 if (runRecorded)
                     return;
                 if (!primaryStashDir)
@@ -204,8 +222,9 @@ export const improveCommand = defineCommand({
                         scopeMode: inferredScopeMode,
                         scopeValue: scopeArg ?? null,
                         dryRun: Boolean(dryRun),
-                        profile: profileArg ?? null,
-                        ...(errorMessage ? { errorMessage } : {}),
+                        strategy: selectedStrategyName,
+                        ...(errorMessage ? { errorMessage: redactSensitiveText(errorMessage, sensitiveValues) } : {}),
+                        sensitiveValues,
                     });
                 }
                 catch (err) {
@@ -223,10 +242,11 @@ export const improveCommand = defineCommand({
             let improveResult;
             try {
                 improveResult = await runImproveSession({
-                    runWork: () => akmImprove({
+                    runWork: () => akmImproveForRun({
                         scope: scopeArg,
                         task: taskArg,
                         dryRun,
+                        resolvedPlan,
                         target: targetArg,
                         autoAccept,
                         ...(runId !== undefined ? { runId } : {}),
@@ -235,7 +255,7 @@ export const improveCommand = defineCommand({
                         ...(minRetrievalCount !== undefined ? { minRetrievalCount } : {}),
                         ...(requireFeedbackSignal ? { requireFeedbackSignal } : {}),
                         ...(skipIfLocked ? { skipIfLocked } : {}),
-                        ...(profileArg !== undefined ? { profile: profileArg } : {}),
+                        ...(strategyArg !== undefined ? { strategy: strategyArg } : {}),
                         ...(Object.keys(syncOverride).length > 0 ? { sync: syncOverride } : {}),
                         consolidateOptions: {
                             target: targetArg,
@@ -249,7 +269,9 @@ export const improveCommand = defineCommand({
                     signalSource: process,
                     exit: process.exit,
                     onTerminate: (reason) => persistTerminated(reason),
-                    ack: (message) => process.stderr.write(`[improve] ${message}; recorded terminated run ${runId}\n`),
+                    ack: (message) => process.stderr.write(dryRun
+                        ? `[improve] ${message}; dry-run state was not persisted\n`
+                        : `[improve] ${message}; recorded terminated run ${runId}\n`),
                 });
             }
             catch (err) {
@@ -264,9 +286,9 @@ export const improveCommand = defineCommand({
                 clearLogFile();
             }
             const durationMs = Date.now() - startedAtMs;
-            if (jsonToStdout) {
-                // Legacy / escape-hatch mode: full JSON on stdout, no file write.
-                // Kept for scripts/agents that already pipe to jq.
+            if (dryRun || jsonToStdout) {
+                // A dry-run never persists its result, so stdout is its only result
+                // channel. --json-to-stdout remains the live-run escape hatch.
                 output("improve", improveResult);
                 process.exit(0);
             }
@@ -288,7 +310,7 @@ export const improveCommand = defineCommand({
             runRecorded = true; // Suppress any late signal-handler write — the success path owns the row now.
             if (primaryStashDir) {
                 try {
-                    writeImproveResultFile(primaryStashDir, runId, improveResult, startedAtIso, profileArg ?? null);
+                    writeImproveResultFile(primaryStashDir, runId, improveResult, startedAtIso, sensitiveValues);
                 }
                 catch (err) {
                     // Stderr warning on the failure path is preferable to crashing

package/dist/commands/improve/improve-result-file.js

@@ -27,6 +27,8 @@
  */
 import crypto from "node:crypto";
 import path from "node:path";
+import { decodeImproveResult } from "../../core/improve-result.js";
+import { redactSensitiveValue } from "../../core/redaction.js";
 import { withStateDb } from "../../core/state-db.js";
 import { recordImproveRun } from "../../storage/repositories/improve-runs-repository.js";
 /**
@@ -74,14 +76,10 @@ export function relativeImproveResultPath(runId) {
  * (closes the dry-run/real-run artifact-trap recorded in MEMORY.md
  * `feedback_akm_dryrun_artifact_trap`).
  *
- * @param profile - The `--profile` value passed to this invocation (e.g.
- * `quick`, `reflect-distill`), or `null`/`undefined` when no profile was
- * given. Mirrors {@link recordTerminatedImproveRun}'s `ctx.profile`
- * convention so successful and terminated runs are equally queryable by
- * profile. Previously hardcoded to `null` here, which meant only
- * abnormally-terminated runs recorded their profile in state.db.
  */
-export function writeImproveResultFile(stashDir, runId, result, startedAt, profile) {
+export function writeImproveResultFile(stashDir, runId, result, startedAt, sensitiveValues = []) {
+    const decoded = decodeImproveResult(result);
+    const persistedResult = redactSensitiveValue(result, sensitiveValues);
     withStateDb((db) => {
         const completedAt = new Date().toISOString();
         // startedAt is the ISO timestamp captured at process launch (passed from the
@@ -95,12 +93,13 @@ export function writeImproveResultFile(stashDir, runId, result, startedAt, profi
             completedAt,
             stashDir,
             dryRun: Boolean(result.dryRun),
-            profile: profile ?? null,
+            legacyProfile: redactSensitiveValue(decoded.legacyProfile, sensitiveValues),
+            strategy: redactSensitiveValue(decoded.strategy, sensitiveValues),
             scopeMode: result.scope?.mode ?? "all",
-            scopeValue: result.scope?.value ?? null,
-            guidance: result.guidance ?? null,
+            scopeValue: persistedResult.scope?.value ?? null,
+            guidance: persistedResult.guidance ?? null,
             ok: Boolean(result.ok),
-            result,
+            result: persistedResult,
         });
     });
     return relativeImproveResultPath(runId);
@@ -124,37 +123,44 @@ export function writeImproveResultFile(stashDir, runId, result, startedAt, profi
  */
 export function recordTerminatedImproveRun(stashDir, runId, startedAt, reason, ctx) {
     const completedAt = new Date().toISOString();
-    const minimalResult = {
-        schemaVersion: 1,
+    const persistedReason = redactSensitiveValue(reason, ctx.sensitiveValues ?? []);
+    const persistedScopeValue = redactSensitiveValue(ctx.scopeValue, ctx.sensitiveValues ?? []);
+    const persistedStrategy = redactSensitiveValue(ctx.strategy, ctx.sensitiveValues ?? []);
+    const minimalResult = redactSensitiveValue({
+        schemaVersion: 2,
         ok: false,
-        scope: { mode: ctx?.scopeMode ?? "all", ...(ctx?.scopeValue ? { value: ctx.scopeValue } : {}) },
-        dryRun: Boolean(ctx?.dryRun),
+        strategy: persistedStrategy,
+        scope: { mode: ctx.scopeMode ?? "all", ...(persistedScopeValue ? { value: persistedScopeValue } : {}) },
+        dryRun: Boolean(ctx.dryRun),
+        memorySummary: { eligible: 0, derived: 0 },
         actions: [],
         plannedRefs: [],
         terminated: {
-            reason,
+            reason: persistedReason,
             at: completedAt,
-            ...(ctx?.errorMessage ? { errorMessage: ctx.errorMessage } : {}),
+            ...(ctx.errorMessage ? { errorMessage: ctx.errorMessage } : {}),
         },
-    };
+    }, ctx.sensitiveValues ?? []);
     withStateDb((db) => {
         recordImproveRun(db, {
             id: runId,
             startedAt,
             completedAt,
             stashDir,
-            dryRun: Boolean(ctx?.dryRun),
-            profile: ctx?.profile ?? null,
-            scopeMode: ctx?.scopeMode ?? "all",
-            scopeValue: ctx?.scopeValue ?? null,
+            dryRun: Boolean(ctx.dryRun),
+            strategy: persistedStrategy,
+            scopeMode: ctx.scopeMode ?? "all",
+            scopeValue: persistedScopeValue ?? null,
             guidance: null,
             ok: false,
             result: minimalResult,
             metadata: {
                 terminated: {
-                    reason,
+                    reason: persistedReason,
                     at: completedAt,
-                    ...(ctx?.errorMessage ? { errorMessage: ctx.errorMessage } : {}),
+                    ...(ctx.errorMessage
+                        ? { errorMessage: redactSensitiveValue(ctx.errorMessage, ctx.sensitiveValues ?? []) }
+                        : {}),
                 },
             },
         });

package/dist/commands/improve/improve-strategies.js

@@ -0,0 +1,137 @@
+// 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 catchup from "../../assets/improve-strategies/catchup.json" with { type: "json" };
+import consolidate from "../../assets/improve-strategies/consolidate.json" with { type: "json" };
+import defaultStrategy from "../../assets/improve-strategies/default.json" with { type: "json" };
+import frequent from "../../assets/improve-strategies/frequent.json" with { type: "json" };
+import graphRefresh from "../../assets/improve-strategies/graph-refresh.json" with { type: "json" };
+import memoryFocus from "../../assets/improve-strategies/memory-focus.json" with { type: "json" };
+import proactiveMaintenance from "../../assets/improve-strategies/proactive-maintenance.json" with { type: "json" };
+import quick from "../../assets/improve-strategies/quick.json" with { type: "json" };
+import recombineOnly from "../../assets/improve-strategies/recombine-only.json" with { type: "json" };
+import reflectDistill from "../../assets/improve-strategies/reflect-distill.json" with { type: "json" };
+import synthesize from "../../assets/improve-strategies/synthesize.json" with { type: "json" };
+import thorough from "../../assets/improve-strategies/thorough.json" with { type: "json" };
+import { parseAssetRef } from "../../core/asset/asset-ref.js";
+import { deepMergeConfig } from "../../core/config/deep-merge.js";
+import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_PROCESS_ENGINE_CAPABILITIES, } from "../../core/config/engine-semantics.js";
+import { ConfigError } from "../../core/errors.js";
+import { resolveImproveProcessRunner, resolveTriageJudgmentRunner, } from "../../integrations/agent/runner.js";
+export const DEFAULT_ALLOWED_TYPES = {
+    reflect: ["agent", "command", "knowledge", "lesson", "memory", "skill", "wiki", "workflow"],
+    distill: ["memory"],
+    consolidate: ["memory"],
+};
+/** Resolve process enablement from the selected strategy, the sole improve authority. */
+export function resolveProcessEnabled(processName, strategy) {
+    const processes = strategy.processes;
+    return processes?.[processName]?.enabled === true;
+}
+export function shouldSkipRef(ref, processName, strategy) {
+    const process = strategy.processes?.[processName];
+    if (process?.enabled === false)
+        return { skip: true, reason: "process-disabled" };
+    const parsed = parseAssetRef(ref);
+    const allowed = process?.allowedTypes ?? DEFAULT_ALLOWED_TYPES[processName];
+    if (!allowed.includes(parsed.type))
+        return { skip: true, reason: "type-filter" };
+    if (parsed.type === "wiki" && parsed.name.split("/")[1] === "raw")
+        return { skip: true, reason: "raw-wiki" };
+    return { skip: false, reason: "" };
+}
+export function isStrategyFilteredForAllPasses(ref, strategy) {
+    return shouldSkipRef(ref, "reflect", strategy).skip && shouldSkipRef(ref, "distill", strategy).skip;
+}
+const BUILTIN_STRATEGIES = {
+    default: defaultStrategy,
+    quick: quick,
+    thorough: thorough,
+    "memory-focus": memoryFocus,
+    "graph-refresh": graphRefresh,
+    frequent: frequent,
+    consolidate: consolidate,
+    catchup: catchup,
+    synthesize: synthesize,
+    "reflect-distill": reflectDistill,
+    "proactive-maintenance": proactiveMaintenance,
+    "recombine-only": recombineOnly,
+};
+if (BUILTIN_IMPROVE_STRATEGY_NAMES.some((name) => !(name in BUILTIN_STRATEGIES))) {
+    throw new Error("Built-in improve strategy names are out of sync with their assets");
+}
+export function resolveImproveStrategy(name, config) {
+    const selectedName = name ?? config.defaults?.improveStrategy ?? "default";
+    const userStrategies = config.improve?.strategies ?? {};
+    if (!(selectedName in BUILTIN_STRATEGIES) && !userStrategies[selectedName]) {
+        const valid = [...new Set([...Object.keys(BUILTIN_STRATEGIES), ...Object.keys(userStrategies)])].sort();
+        throw new ConfigError(`Improve strategy "${selectedName}" not found. Valid strategies: ${valid.join(", ")}.`, "UNKNOWN_IMPROVE_STRATEGY");
+    }
+    const baseStrategy = BUILTIN_STRATEGIES[selectedName] ?? BUILTIN_STRATEGIES.default;
+    const resolved = deepMergeConfig(baseStrategy, (userStrategies[selectedName] ?? {}));
+    return { name: selectedName, config: resolved };
+}
+export function resolveStrategyProcessEnabled(strategy, processName) {
+    return resolveProcessEnabled(processName, strategy.config);
+}
+function cloneAndFreeze(value) {
+    const clone = structuredClone(value);
+    const freeze = (item) => {
+        if (typeof item !== "object" || item === null || Object.isFrozen(item))
+            return;
+        for (const child of Object.values(item))
+            freeze(child);
+        Object.freeze(item);
+    };
+    freeze(clone);
+    return clone;
+}
+/** Resolve every enabled process structurally before improve emits signals or performs I/O. */
+export function resolveImprovePlan(name, config, options = {}) {
+    const strategy = resolveImproveStrategy(name, config);
+    return buildImprovePlan(strategy, config, options);
+}
+function buildImprovePlan(strategy, config, options) {
+    const processes = {};
+    for (const processName of Object.keys(IMPROVE_PROCESS_ENGINE_CAPABILITIES)) {
+        const processConfig = cloneAndFreeze(strategy.config.processes?.[processName] ?? {});
+        const enabled = processConfig.enabled === true;
+        let runner = null;
+        if (IMPROVE_PROCESS_ENGINE_CAPABILITIES[processName] !== "llm" || !enabled) {
+            processes[processName] = Object.freeze({ enabled, config: processConfig, runner });
+            continue;
+        }
+        // Validation itself is structural and always runs. Only its optional repair
+        // step needs a model, so disabling repair must not create an LLM preflight.
+        if (processName !== "validation" || options.repairValidationFailures !== false) {
+            runner = resolveImproveProcessRunner(strategy.config, processName, config);
+        }
+        if (!runner && !(processName === "validation" && options.repairValidationFailures === false)) {
+            throw new ConfigError(`Enabled improve process "${processName}" requires an LLM engine. Set defaults.llmEngine or improve.strategies.${strategy.name}.processes.${processName}.engine.`, "LLM_NOT_CONFIGURED");
+        }
+        if (runner)
+            runner = cloneAndFreeze(runner);
+        processes[processName] = Object.freeze({ enabled, config: processConfig, runner });
+    }
+    const triage = strategy.config.processes?.triage;
+    const judgmentOptedIn = triage !== undefined && Object.hasOwn(triage, "judgment");
+    const triageJudgment = processes.triage.enabled && judgmentOptedIn
+        ? resolveTriageJudgmentRunner(triage.judgment, config, triage, strategy.config)
+        : null;
+    if (processes.triage.enabled && judgmentOptedIn && !triageJudgment) {
+        throw new ConfigError(`Enabled improve triage judgment requires an engine. Set defaults.llmEngine or improve.strategies.${strategy.name}.processes.triage.judgment.engine.`, "LLM_NOT_CONFIGURED");
+    }
+    const frozenProcesses = Object.freeze(processes);
+    const frozenStrategy = Object.freeze({
+        name: strategy.name,
+        config: cloneAndFreeze({
+            ...strategy.config,
+            processes: Object.fromEntries(Object.entries(frozenProcesses).map(([name, process]) => [name, process.config])),
+        }),
+    });
+    return Object.freeze({
+        strategy: frozenStrategy,
+        processes: frozenProcesses,
+        triageJudgment: triageJudgment ? cloneAndFreeze(triageJudgment) : null,
+    });
+}