akm-cli 0.9.30 → 0.10.26101001-alpha

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

@@ -3,20 +3,20 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import path from "node:path";
 import { defineCommand } from "citty";
-import { getParsedInvocation } from "../../cli/invocation.js";
-import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
-import { GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { findCittyTopLevelCommandIndex, getStringArg, hasSubcommand, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { defineJsonCommand, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
 import { isFullRefInput, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { loadConfig } from "../../core/config/config.js";
 import { ConfigError, UsageError } from "../../core/errors.js";
 import { resolveMutationTarget } from "../../core/mutation-target.js";
 import { getCacheDir } from "../../core/paths.js";
 import { redactSensitiveText } from "../../core/redaction.js";
-import { clearLogFile, setLogFile, warn } from "../../core/warn.js";
+import { clearLogFile, setLogFile } from "../../core/warn.js";
 import { resolveWriteTarget } from "../../core/write-source.js";
 import { DEFAULT_LLM_TIMEOUT_MS } from "../../integrations/agent/config.js";
 import { defaultWhich } from "../../integrations/agent/detect.js";
-import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
+import { collectEngineCredentialValues, materializeLlmConnection, } from "../../integrations/agent/engine-resolution.js";
+import { llmUseFromRunner, sdkFallbackUseFromRunner } from "../../integrations/agent/runner.js";
 import { probeLlmReachable } from "../../llm/client.js";
 import { getOutputMode } from "../../output/context.js";
 import { deliverRendered } from "../../output/html-render.js";
@@ -34,37 +34,6 @@ let akmImproveForRun = akmImprove;
 export function _setAkmImproveForTests(fake) {
     akmImproveForRun = fake ?? akmImprove;
 }
-/**
- * `--auto-accept` (removed in 0.9): citty absorbs it silently, and
- * `--auto-accept 90` would leave `90` as the scope — a 0.8-era crontab would
- * match nothing and exit 0. Warn, and drop that positional.
- */
-function resolveScopeAfterRetiredAutoAccept(scopeArg) {
-    const invocation = getParsedInvocation();
-    const autoAcceptRaw = invocation.getFlagValue("--auto-accept");
-    if (autoAcceptRaw === undefined && !invocation.hasFlag("--auto-accept"))
-        return scopeArg;
-    warn("[improve] --auto-accept was removed in 0.9 and is ignored; proposals always queue for review. " +
-        "Replacement: `akm improve && akm proposal drain --promote --yes`, or a `triage` block with " +
-        'applyMode: "promote" in your strategy. It becomes a hard error in 0.10.');
-    if (scopeArg !== undefined && scopeArg === autoAcceptRaw) {
-        warn(`[improve] ignoring "${scopeArg}" as a scope — it is the removed --auto-accept flag's value.`);
-        return undefined;
-    }
-    return scopeArg;
-}
-/** `akm improve canary` (removed in 0.9) would otherwise be a type scope matching nothing, exiting 0. */
-function rejectRetiredCanaryScope(scopeArg) {
-    if (scopeArg !== "canary")
-        return;
-    throw new UsageError('"akm improve canary" was removed in 0.9; the collapse-detector canary set it managed no longer exists.', "INVALID_FLAG_VALUE");
-}
-/** `--target` (renamed `--bundle` in 0.9) would otherwise be absorbed and write to the default bundle. */
-function rejectRetiredImproveTargetFlag() {
-    if (!getParsedInvocation().hasFlag("--target"))
-        return;
-    throw new UsageError("`akm improve --target` was renamed to `--bundle` in 0.9. Use `--bundle <name>` instead.", "INVALID_FLAG_VALUE");
-}
 /**
  * `--require-engines` (#957): fail before any side effect when an enabled
  * process cannot run, naming what each is missing — a scheduled run would
@@ -81,18 +50,36 @@ function collectRequiredEngineTargets(plan) {
     const runners = Object.entries(plan.processes)
         .flatMap(([processName, process]) => (process.runner ? [[processName, process.runner]] : []))
         .concat(plan.triageJudgment ? [["triage.judgment", plan.triageJudgment]] : []);
-    return runners.map(([processName, runner]) => ({
-        process: processName,
-        engine: runner.engine,
-        ...(runner.kind === "llm" ? { connection: probeConnection(runner) } : { bin: runner.profile.bin }),
-        ...(runner.kind === "sdk" && runner.fallbackConnection
-            ? { connection: probeConnection({ connection: runner.fallbackConnection, timeoutMs: runner.fallbackTimeoutMs }) }
-            : {}),
-    }));
+    return runners.map(([processName, runner]) => {
+        // The runner's own timeout, else the connection's (sdkFallbackUseFromRunner already does this).
+        const use = runner.kind === "llm"
+            ? {
+                ...llmUseFromRunner(runner),
+                timeoutMs: runner.timeoutMs !== undefined ? runner.timeoutMs : (runner.connection.timeoutMs ?? null),
+            }
+            : runner.kind === "sdk"
+                ? sdkFallbackUseFromRunner(runner)
+                : undefined;
+        return {
+            process: processName,
+            engine: runner.engine,
+            ...(runner.kind === "llm" ? {} : { bin: runner.profile.bin }),
+            ...(use ? probeConnection(use) : {}),
+        };
+    });
 }
-/** The resolved engine keeps its request timeout beside the connection (the runtime merges it in); the probe needs it on the connection. */
-function probeConnection(runner) {
-    return runner.timeoutMs !== undefined ? { ...runner.connection, timeoutMs: runner.timeoutMs } : runner.connection;
+/**
+ * The connection the probe sends, built as a dispatch builds it: the runner
+ * keeps its credential symbolic, so the key is read and injected here, or the
+ * probe would go out without one.
+ */
+function probeConnection(use) {
+    try {
+        return { connection: materializeLlmConnection(use) };
+    }
+    catch (err) {
+        return { connection: use.connection, error: err instanceof Error ? err.message : String(err) };
+    }
 }
 /**
  * The bound on `--require-engines`' probe: the connection's own request
@@ -133,6 +120,8 @@ export async function assertRequiredEnginesReachable(plan, probeReachable = (con
         }
         if (!target.connection)
             return { ...target, reach: { reachable: true }, latencyMs: 0 };
+        if (target.error)
+            return { ...target, reach: { reachable: false, error: target.error }, latencyMs: 0 };
         return { ...target, ...(await probeConnectionOnce(target.connection)) };
     }));
     const unreachable = probed.filter((item) => !item.reach.reachable);
@@ -173,53 +162,91 @@ async function runShowPromptCli(refArg, parsedRef, taskArg, targetArg, resolvedP
     });
 }
 /** `akm improve report` (#944): the per-run LLM usage/routing report ("report" is no asset type). */
-function runImproveReportCli(args) {
-    const runIdArg = getStringArg(args, "run");
-    const sinceArg = getStringArg(args, "since");
-    const result = runImproveReportQuery({ runId: runIdArg, since: sinceArg });
-    output("improve-report", { ok: true, ...result });
-}
-/** `--run`/`--since` belong to `improve report`; elsewhere citty would silently ignore them. */
-function rejectReportOnlyFlags(args) {
-    const flag = getStringArg(args, "run") !== undefined
-        ? "--run"
-        : getStringArg(args, "since") !== undefined
-            ? "--since"
-            : undefined;
-    if (flag === undefined)
-        return;
-    throw new UsageError(`\`${flag}\` only applies to \`akm improve report\`. Use \`akm improve report ${flag} <value>\` instead.`, "INVALID_FLAG_VALUE");
-}
+const improveReportCommand = defineJsonCommand({
+    meta: {
+        name: "report",
+        description: "Show the LLM usage/routing report for the most recent improve run, one run, or a window of runs.",
+    },
+    args: {
+        run: {
+            type: "string",
+            description: "Show the report for one specific improve_runs row instead of the most recent run. Mutually exclusive with --since.",
+        },
+        since: {
+            type: "string",
+            description: 'Aggregate the report over every real run started since <window> (a duration like "24h"/"7d", or an ISO timestamp) instead of showing one run. Mutually exclusive with --run.',
+        },
+    },
+    run({ args }) {
+        const result = runImproveReportQuery({ runId: getStringArg(args, "run"), since: getStringArg(args, "since") });
+        output("improve-report", { ok: true, ...result });
+    },
+});
 /**
  * `akm improve judge`: reflect's quality judge on one revision, read as
  * `{"source", "candidate", "feedback"}` JSON from stdin, with the engine the
  * strategy's reflect quality gate names. It writes nothing.
  */
-async function runImproveJudgeCli(strategyName) {
-    const input = process.stdin.isTTY
-        ? {}
-        : JSON.parse((await readStdin()).toString("utf8"));
-    const { source, candidate, feedback, ref } = input;
-    if (typeof source !== "string" || typeof candidate !== "string") {
-        throw new UsageError('`akm improve judge` reads {"source": "...", "candidate": "...", "feedback": "...", "ref": "..."} JSON from stdin.', "MISSING_REQUIRED_ARGUMENT");
-    }
-    const config = loadConfig();
-    const judge = resolveQualityGateJudge(config, resolveImproveStrategy(strategyName, config).config, "reflect");
-    if (!judge) {
-        throw new ConfigError("`akm improve judge` judges with the reflect quality gate's engine. Set processes.reflect.qualityGate.engine.", "INVALID_CONFIG_FILE");
-    }
-    const notes = typeof feedback === "string" && feedback.trim() !== "" ? [feedback.trim()] : [];
-    const verdict = await runReflectQualityJudge(config, candidate, source, notes, undefined, {
-        runnerSelectionFrozen: true,
-        llmRunner: judge,
-        ...(typeof ref === "string" && ref ? { ref } : {}),
-    });
-    output("improve-judge", { engine: judge.engine, ...verdict });
-}
+const improveJudgeCommand = defineJsonCommand({
+    meta: {
+        name: "judge",
+        description: "Run reflect's quality judge on one revision, read as {source, candidate, feedback, ref} JSON from stdin. Writes nothing.",
+    },
+    args: {
+        strategy: {
+            type: "string",
+            description: "Named improve strategy whose reflect quality gate names the judge engine.",
+        },
+    },
+    async run({ args }) {
+        const input = process.stdin.isTTY
+            ? {}
+            : JSON.parse((await readStdin()).toString("utf8"));
+        const { source, candidate, feedback, ref } = input;
+        if (typeof source !== "string" || typeof candidate !== "string") {
+            throw new UsageError('`akm improve judge` reads {"source": "...", "candidate": "...", "feedback": "...", "ref": "..."} JSON from stdin.', "MISSING_REQUIRED_ARGUMENT");
+        }
+        const config = loadConfig();
+        const judge = resolveQualityGateJudge(config, resolveImproveStrategy(getStringArg(args, "strategy"), config).config, "reflect");
+        if (!judge) {
+            throw new ConfigError("`akm improve judge` judges with the reflect quality gate's engine. Set processes.reflect.qualityGate.engine.", "INVALID_CONFIG_FILE");
+        }
+        const notes = typeof feedback === "string" && feedback.trim() !== "" ? [feedback.trim()] : [];
+        const verdict = await runReflectQualityJudge(config, candidate, source, notes, undefined, {
+            runnerSelectionFrozen: true,
+            llmRunner: judge,
+            ...(typeof ref === "string" && ref ? { ref } : {}),
+        });
+        output("improve-judge", { engine: judge.engine, ...verdict });
+    },
+});
+/** The subcommands `setup` withheld for this run, restored by `cleanup` (one command runs per process; in-process tests run many). */
+let subCommandsWithheld = false;
+const IMPROVE_SUBCOMMANDS = { report: improveReportCommand, judge: improveJudgeCommand };
 export const improveCommand = defineCommand({
     meta: {
         name: "improve",
-        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when the selected strategy enables consolidate.",
+        description: "Analyze existing AKM assets and generate improvement proposals; also consolidates memories when the selected strategy enables consolidate. `improve report` and `improve judge` are subcommands.",
+    },
+    subCommands: IMPROVE_SUBCOMMANDS,
+    // `improve` takes a scope positional (an asset type or ref), and citty reads
+    // the first positional of a command with subcommands as a subcommand name,
+    // failing with an unknown command for a scope. So the subcommands stay
+    // registered only for an invocation that names one; any other, scope or none,
+    // is the improve run itself.
+    setup(context) {
+        const index = findCittyTopLevelCommandIndex(context.rawArgs, improveCommand.args);
+        const token = index >= 0 ? context.rawArgs[index] : undefined;
+        if (token !== undefined && token in IMPROVE_SUBCOMMANDS)
+            return;
+        subCommandsWithheld = true;
+        context.cmd.subCommands = undefined;
+    },
+    cleanup(context) {
+        if (!subCommandsWithheld)
+            return;
+        context.cmd.subCommands = IMPROVE_SUBCOMMANDS;
+        subCommandsWithheld = false;
     },
     // Declared explicitly: otherwise citty takes `--format`'s value as the scope.
     args: {
@@ -231,11 +258,6 @@ export const improveCommand = defineCommand({
         },
         task: { type: "string", description: "Add extra guidance for this improvement pass" },
         "dry-run": { type: "boolean", description: "Show planned actions without writing", default: false },
-        plan: {
-            type: "boolean",
-            description: "Alias for --dry-run (#947). Sets the exact same internal flag; use it when previewing resolved process -> engine -> model routing (plan.processes) rather than checking what would write.",
-            default: false,
-        },
         bundle: {
             type: "string",
             description: "Bundle to improve and write proposals to (default: defaultWriteTarget, else the working bundle); only its assets are planned",
@@ -247,7 +269,7 @@ export const improveCommand = defineCommand({
         },
         "require-feedback-signal": {
             type: "boolean",
-            description: "Turn the proactive/high-salience fallback lanes off (they only select and score assets; a rewrite needs negative feedback)",
+            description: "Turn the proactive-maintenance lane off for this run, so only assets with recent feedback are planned",
             default: false,
         },
         "json-to-stdout": {
@@ -270,17 +292,9 @@ export const improveCommand = defineCommand({
             description: "Print the composed reflect prompt for one asset ref and exit — no lock, index write, or engine dispatch (#952). Requires a fully-qualified asset ref as the scope positional (e.g. `akm improve lessons/my-lesson --show-prompt`). JSON/yaml format carries the prompt as a `prompt` field; text format prints it directly.",
             default: false,
         },
-        run: {
-            type: "string",
-            description: 'Only with the "report" scope (`akm improve report --run <id>`): show the LLM usage/routing report for one specific improve_runs row instead of the most recent run. Mutually exclusive with --since.',
-        },
-        since: {
-            type: "string",
-            description: 'Only with the "report" scope (`akm improve report --since <window>`): aggregate the LLM usage/routing report over every real run started since <window> (a duration like "24h"/"7d", or an ISO timestamp) instead of showing one run. Mutually exclusive with --run.',
-        },
         strategy: {
             type: "string",
-            description: "Named improve strategy from improve.strategies or built-in strategies (catchup, consolidate, default, proactive-maintenance, quick, reflect-distill, thorough). Controls which sub-processes run and which asset types are processed.",
+            description: "Named improve strategy from improve.strategies or built-in strategies (consolidate, default). Controls which sub-processes run and which asset types are processed.",
         },
         sync: {
             type: "boolean",
@@ -293,29 +307,21 @@ export const improveCommand = defineCommand({
     },
     async run({ args }) {
         await runWithJsonErrors(async () => {
-            if (getStringArg(args, "scope") === "report") {
-                runImproveReportCli(args);
+            // citty runs this body after a subcommand it dispatched too.
+            if (hasSubcommand(args, new Set(Object.keys(IMPROVE_SUBCOMMANDS))))
                 return;
-            }
-            rejectReportOnlyFlags(args);
-            if (getStringArg(args, "scope") === "judge") {
-                await runImproveJudgeCli(getStringArg(args, "strategy"));
-                return;
-            }
-            rejectRetiredImproveTargetFlag();
             const jsonToStdout = args["json-to-stdout"];
             const targetArg = getStringArg(args, "bundle");
             const taskArg = getStringArg(args, "task");
-            // `--plan` is an alias for `--dry-run`; `--show-prompt` is read-only too.
-            const dryRun = args["dry-run"] || args.plan || args["show-prompt"];
+            // `--show-prompt` is read-only too.
+            const dryRun = args["dry-run"] || args["show-prompt"];
             const limitRaw = parsePositiveIntFlag(args.limit ?? undefined);
             const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
             const requireFeedbackSignal = args["require-feedback-signal"];
             const skipIfLocked = args["skip-if-locked"];
             const strategyArg = getStringArg(args, "strategy");
             const effectiveConfig = loadConfig();
-            const scopeArg = resolveScopeAfterRetiredAutoAccept(getStringArg(args, "scope"));
-            rejectRetiredCanaryScope(scopeArg);
+            const scopeArg = getStringArg(args, "scope");
             const scopeRef = scopeArg && isFullRefInput(scopeArg) ? parseRefInput(scopeArg) : undefined;
             const writeTarget = dryRun
                 ? undefined

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

@@ -1,17 +1,12 @@
 // 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 proactiveMaintenance from "../../assets/improve-strategies/proactive-maintenance.json" with { type: "json" };
-import quick from "../../assets/improve-strategies/quick.json" with { type: "json" };
-import reflectDistill from "../../assets/improve-strategies/reflect-distill.json" with { type: "json" };
-import thorough from "../../assets/improve-strategies/thorough.json" with { type: "json" };
 import { conceptIdFromTypeName, parseRefInput } from "../../core/asset/resolve-ref.js";
 import { ImproveProfileConfigSchema } from "../../core/config/config-schema.js";
 import { deepMergeConfig } from "../../core/config/deep-merge.js";
-import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_ENGINE_PROCESSES, IMPROVE_PROCESS_NAMES, } from "../../core/config/engine-semantics.js";
+import { BUILTIN_IMPROVE_STRATEGY_NAMES, IMPROVE_ENGINE_PROCESSES, IMPROVE_PROCESS_NAMES, REMOVED_IMPROVE_STRATEGY_NAMES, } from "../../core/config/engine-semantics.js";
 import { ConfigError } from "../../core/errors.js";
 import { describeLlmCredentialAvailability, } from "../../integrations/agent/engine-resolution.js";
 import { runnerLlmConnection } from "../../integrations/agent/runner.js";
@@ -69,12 +64,7 @@ export function isStrategyFilteredForAllPasses(ref, strategy) {
 }
 const BUILTIN_STRATEGIES = {
     default: defaultStrategy,
-    quick,
-    thorough,
     consolidate,
-    catchup,
-    "reflect-distill": reflectDistill,
-    "proactive-maintenance": proactiveMaintenance,
 };
 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");
@@ -105,6 +95,11 @@ export function resolveImproveStrategy(name, config) {
         // shape this refusal exists to reject, not a way around it.
         "Choose a different strategy. `graph-refresh` cannot be redefined under `improve.strategies` — it always refuses.");
     }
+    if (!(selectedName in BUILTIN_STRATEGIES) &&
+        !userStrategies[selectedName] &&
+        REMOVED_IMPROVE_STRATEGY_NAMES.includes(selectedName)) {
+        throw new ConfigError(`Improve strategy "${selectedName}" was removed in 0.10. Use "default" (or "consolidate"), or define "${selectedName}" under improve.strategies to keep your own version.`, "UNKNOWN_IMPROVE_STRATEGY", `Run \`akm improve --strategy default\`, or add \`improve.strategies.${selectedName}\` to your config; a block of that name is a user-defined strategy that inherits \`default\`.`);
+    }
     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");
@@ -304,7 +299,8 @@ function buildImprovePlan(strategy, config, options) {
         });
     }
     if (engineUnavailable.length > 0 &&
-        !Object.values(processes).some((process) => process.enabled) &&
+        // proactiveMaintenance uses no engine: it is a selector, so it alone does not keep a run alive.
+        !IMPROVE_ENGINE_PROCESSES.some((name) => processes[name].enabled) &&
         (!options.allowAllDisabled || anyEngineNotConfigured)) {
         const names = engineUnavailable.map((item) => `"${item.process}"`).join(", ");
         throw new ConfigError(`No improve process can run: ${names} ${engineUnavailable.length === 1 ? "requires" : "require"} an engine that is not configured. Set defaults.llmEngine, or the per-process engine key named for each.`, "LLM_NOT_CONFIGURED");

package/dist/commands/improve/loop-stages.js

@@ -148,7 +148,6 @@ async function runLoopReflectPass(planned, env, tally) {
         ...(options.sourceName && primaryStashDir ? { target: { source: options.sourceName, root: primaryStashDir } } : {}),
         ...(reflectErrors.length > 0 ? { avoidPatterns: [...reflectErrors] } : {}),
         eventSource: "improve",
-        lowValueFilter: improveProfile.processes?.reflect?.lowValueFilter?.enabled === true,
         ...(improveProfile.processes?.reflect?.defectFilter
             ? { defectFilter: improveProfile.processes.reflect.defectFilter }
             : {}),

package/dist/commands/improve/planner.js

@@ -99,7 +99,6 @@ export function buildImproveExecutionPlan(input) {
             effective: { ...input.consolidation.effective },
             gates: {
                 profile: { ...input.consolidation.gates.profile },
-                minimumPool: { ...input.consolidation.gates.minimumPool },
                 delta: { ...input.consolidation.gates.delta },
             },
         },