akm-cli 0.9.28-alpha.1 → 0.9.28-alpha.2

package/dist/cli/shared.js

@@ -10,6 +10,7 @@
 import { defineCommand } from "citty";
 import { stringify as yamlStringify } from "yaml";
 import { renderHealthHtml } from "../commands/health/renderers.js";
+import { renderMetricsHtml } from "../commands/metrics/html-report.js";
 import { assertNever } from "../core/assert.js";
 import { AkmError, UsageError } from "../core/errors.js";
 import { getOutputMode } from "../output/context.js";
@@ -331,10 +332,10 @@ export function output(command, result) {
             return;
         }
         case "html": {
-            // `akm health` is the only command with a bespoke HTML report, so it is
-            // called directly rather than through a registry with one possible
-            // registrant (see `output/render-registry.ts`).
-            const rendered = command === "health" ? renderHealthHtml(shaped) : null;
+            // `akm health` and `akm metrics` are the only commands with a bespoke
+            // HTML report, so they are called directly rather than through a
+            // registry with two possible registrants (see `output/render-registry.ts`).
+            const rendered = command === "health" ? renderHealthHtml(shaped) : command === "metrics" ? renderMetricsHtml(shaped) : null;
             deliverRendered(rendered ?? renderGenericHtml(command, shaped), mode.outputPath);
             return;
         }

package/dist/cli.js

@@ -70,8 +70,10 @@ import { secretCommand } from "./commands/env/secret-cli.js";
 import { feedbackCommand } from "./commands/feedback-cli.js";
 import { akmHealth } from "./commands/health.js";
 import "./commands/health/renderers.js";
+import "./commands/metrics/md-report.js";
 import { parseWindowSpec } from "./commands/health/windows.js";
 import { improveCommand } from "./commands/improve/improve-cli.js";
+import { metricsCommand } from "./commands/metrics/metrics-cli.js";
 import { migrateCommand } from "./commands/migrate-cli.js";
 import { modelsCommand } from "./commands/models-cli.js";
 import { logCommand } from "./commands/observability-cli.js";
@@ -94,6 +96,7 @@ import { DURATION_UNITS, parseDuration } from "./core/time.js";
 import { plainize } from "./core/tty.js";
 import { info, isQuiet, setQuiet, setVerbose, warn } from "./core/warn.js";
 import { disposeDispatchResources } from "./integrations/agent/runner-dispatch.js";
+import { installLlmUsagePersistenceIfAbsent } from "./llm/usage-persist.js";
 import { EMBEDDED_HINTS, EMBEDDED_HINTS_FULL } from "./output/cli-hints.js";
 import { getOutputMode, initOutputMode, parseDetailLevel } from "./output/context.js";
 import { isFormatExemptCommand } from "./output/format-exempt.js";
@@ -448,6 +451,7 @@ const commands = {
     setup: setupCommand,
     index: indexCommand,
     health: healthCommand,
+    metrics: metricsCommand,
     info: infoCommand,
     bundle: bundleCommand,
     upgrade: upgradeCommand,
@@ -795,6 +799,7 @@ const HELP_SECTIONS = [
             "index",
             "lint",
             "health",
+            "metrics",
             "config",
             "models",
             "registry",
@@ -965,7 +970,7 @@ export function normalizeCittyCliError(error, rawArgs) {
  * and returns, every direct call site here needs its own explicit `return;`
  * to stop the rest of startup from running after a fatal early error.
  */
-async function runCli() {
+export async function runCli() {
     try {
         process.argv = consumeSchedulerContextArg(process.argv);
     }
@@ -1056,6 +1061,10 @@ async function runCli() {
         console.error(plainize("👋 First time with akm? Run `akm setup` to get started.\n   Docs: https://github.com/itlackey/akm#readme\n"));
     })();
     const rawArgs = process.argv.slice(2);
+    // Persist LLM usage for every command, not only `improve` and `proposal
+    // drain`. A per-run sink installed inside a command layers over this one and
+    // restores it on dispose.
+    const disposeLlmUsageSink = installLlmUsagePersistenceIfAbsent();
     try {
         if (rawArgs.length === 0) {
             process.stdout.write(`${await renderSectionedRootHelp()}\n`);
@@ -1119,6 +1128,7 @@ async function runCli() {
         emitJsonError(error);
     }
     finally {
+        disposeLlmUsageSink();
         await disposeDispatchResources();
     }
 }

package/dist/commands/health/accept-rate.js

@@ -16,18 +16,22 @@
  */
 import { resolveStashDir } from "../../core/common.js";
 import { isProceduralRejection } from "../proposal/proposal-types.js";
-import { listProposals } from "../proposal/repository.js";
+import { listProposals, listProposalsReadOnly } from "../proposal/repository.js";
 /**
  * Compute accept-rate-per-source metrics from the proposal store. Defaults to
  * the configured default stash when `stashDir` is omitted (same resolution
- * `akm health` already uses for the rest of its report).
+ * `akm health` already uses for the rest of its report). A caller that passes
+ * `ctx` reads through {@link listProposalsReadOnly}, which never opens
+ * state.db for writing (`akm metrics`).
  */
-export function computeAcceptRateBySource(stashDir) {
+export function computeAcceptRateBySource(stashDir, ctx) {
     const stash = stashDir ?? resolveStashDir();
     const bySource = new Map();
     const countProposals = (statuses, includeArchive) => {
         for (const status of statuses) {
-            const proposals = listProposals(stash, { status, includeArchive });
+            const proposals = ctx
+                ? listProposalsReadOnly(stash, { status, includeArchive }, ctx)
+                : listProposals(stash, { status, includeArchive });
             for (const p of proposals) {
                 // A stale-target auto-reject (STALE, R20) is procedural, not a
                 // judgement on the content — counting it would understate the

package/dist/commands/health/html-report.js

@@ -26,15 +26,10 @@
  * pointed at the jsDelivr CDN, so viewing the report now requires network
  * access. There is no env var or option to opt back into an offline report.
  */
-import { escapeHtml } from "../../output/html-render.js";
+import { escapeHtml, isoTimeTag } from "../../output/html-render.js";
 import { pkgVersion } from "../../version.js";
 import { buildHealthReportViewModel, compact, fmtMs, humanize, num, } from "./report-view-model.js";
 const esc = escapeHtml;
-/** Emit a <time> element that the browser's JS will reformat to the viewer's local timezone. */
-function isoTimeTag(iso) {
-    const fallback = iso.slice(0, 16).replace("T", " ");
-    return `<time data-iso="${esc(iso)}">${esc(fallback)}</time>`;
-}
 function trendClass(direction) {
     return direction === "up" ? "trend-up" : direction === "down" ? "trend-down" : "trend-flat";
 }
@@ -79,8 +74,8 @@ const badgeByStatus = {
 };
 // ── ECharts delivery ─────────────────────────────────────────────────────────
 const ECHARTS_CDN = "https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js";
-/** Always CDN — see the module docstring's chunk-9 WI-9.4d note. */
-function buildEchartsTag() {
+/** Always CDN — see the module docstring's chunk-9 WI-9.4d note. Shared with the metrics dashboard. */
+export function buildEchartsTag() {
     return `<script src="${ECHARTS_CDN}"></script>`;
 }
 /**

package/dist/commands/health/llm-usage.js

@@ -68,7 +68,7 @@ export function readLlmUsageAggregate(stateDbPath, since, until) {
     return summarizeLlmUsage(events);
 }
 /**
- * Aggregate `llm_usage` events (#576) into a process x engine x model
+ * Aggregate `llm_usage` records (#576) into a process x engine x model
  * cross-tab (#944) — one row per distinct `(process, engine, model)` triple
  * seen, each carrying the same call/failure/token/duration totals as
  * {@link LlmUsageStageAggregate}. A call missing any one of the three
@@ -78,12 +78,9 @@ export function readLlmUsageAggregate(stateDbPath, since, until) {
  * breakdowns — `akm health`'s existing consumers of those stay untouched.
  * Row order is insertion order (first `(process, engine, model)` triple seen).
  */
-export function summarizeLlmUsageCrossTab(events) {
+export function summarizeLlmUsageRecordsCrossTab(records) {
     const rows = new Map();
-    for (const event of events) {
-        const record = decodeLlmUsageRecord(event.metadata);
-        if (!record)
-            continue;
+    for (const record of records) {
         const process = record.process ?? UNATTRIBUTED_STAGE;
         const engine = record.engine ?? UNATTRIBUTED_STAGE;
         const model = record.model ?? UNATTRIBUTED_STAGE;
@@ -104,3 +101,17 @@ export function summarizeLlmUsageCrossTab(events) {
     }
     return [...rows.values()];
 }
+/**
+ * The events form of {@link summarizeLlmUsageRecordsCrossTab}: decode each
+ * `llm_usage` event's metadata (dropping undecodable rows) and aggregate the
+ * records. Use it when only persisted events are available.
+ */
+export function summarizeLlmUsageCrossTab(events) {
+    const records = [];
+    for (const event of events) {
+        const record = decodeLlmUsageRecord(event.metadata);
+        if (record)
+            records.push(record);
+    }
+    return summarizeLlmUsageRecordsCrossTab(records);
+}

package/dist/commands/health/renderers.js

@@ -15,10 +15,10 @@
  *
  * The Markdown renderer registers into the shared per-command registry (D7,
  * `../../output/render-registry.ts`) alongside every other command's `--format
- * md` renderer. The HTML renderer does not: `health` was, and remains, the
- * only command with a bespoke HTML report, so `cli/shared.ts` calls
- * {@link renderHealthHtml} directly instead of going through a registry with
- * exactly one possible registrant.
+ * md` renderer. The HTML renderer does not: `health` and `metrics` are the only
+ * commands with a bespoke HTML report, so `cli/shared.ts` calls
+ * {@link renderHealthHtml} (and `renderMetricsHtml`) directly instead of going
+ * through a registry with two possible registrants.
  *
  * Returning `null` falls through to the generic renderer, so a result without
  * the report dataset still renders — generically — instead of erroring or

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

@@ -25,8 +25,10 @@ import { summarizeLlmUsageCrossTab } from "../health/llm-usage.js";
 const PRE_USAGE_REPORT_NOTE = "eligibility reasons unavailable for runs recorded before 0.9.15";
 const TERMINATED_RUN_NOTE = "run terminated before completion; no usage report was recorded";
 /**
- * Recompute the cross-tab from this run's own `llm_usage` events (a pre-#944
- * row has no persisted one). `eventsCtx` threads the state.db connection
+ * Recompute the cross-tab from the `llm_usage` events in this run's wall-clock
+ * window (a pre-#944 row has no persisted one). Events carry no run id, so a
+ * recomputed cross-tab can include LLM calls that other akm processes made
+ * during the run's window. `eventsCtx` threads the state.db connection
  * `runImproveReportQuery` already holds via `withStateDb`, so a `--since`
  * window with several pre-0.9.15 or undecodable rows reads through that one
  * open connection instead of each row opening and closing its own.

package/dist/commands/improve/improve.js

@@ -11,7 +11,7 @@ import path from "node:path";
 import { parseRefInput } from "../../core/asset/resolve-ref.js";
 import { bundlesToSourceEntries, loadConfig } from "../../core/config/config.js";
 import { ConfigError, rethrowIfTestIsolationError, UsageError } from "../../core/errors.js";
-import { appendEvent, readEvents } from "../../core/events.js";
+import { appendEvent } from "../../core/events.js";
 import { classifyImproveAction, foldDistillSkipped } from "../../core/improve-types.js";
 import { resolveMutationTarget } from "../../core/mutation-target.js";
 import { getDbPath, getStashLocksDir, getStateDbPathInDataDir } from "../../core/paths.js";
@@ -26,13 +26,13 @@ import { akmIndex } from "../../indexer/indexer.js";
 import { collectPendingMemories } from "../../indexer/passes/memory-inference.js";
 import { resolveEntryContentDir, resolveSourceEntries } from "../../indexer/search/search-source.js";
 import { collectEngineCredentialValues } from "../../integrations/agent/engine-resolution.js";
-import { installLlmUsagePersistence, LLM_USAGE_EVENT } from "../../llm/usage-persist.js";
+import { installLlmUsagePersistence } from "../../llm/usage-persist.js";
 import { withLlmStage } from "../../llm/usage-telemetry.js";
 import { isGitBackedStash, listGitChangedPaths, resolveWritableOverride, saveGitStash, } from "../../sources/providers/git.js";
 import { closeDatabase, openExistingDatabase } from "../../storage/repositories/index-connection.js";
 import { getEntryCount } from "../../storage/repositories/index-entries-repository.js";
 import { openSqliteReadSnapshot, SqliteReadSnapshotUnavailableError } from "../../storage/sqlite-read-snapshot.js";
-import { summarizeLlmUsageCrossTab } from "../health/llm-usage.js";
+import { summarizeLlmUsageRecordsCrossTab } from "../health/llm-usage.js";
 import { drainProposals } from "../proposal/drain.js";
 import { describeGatedLanes, isAutonomyLaneAllowed } from "./autonomy-gate.js";
 import { akmDistill } from "./distill.js";
@@ -118,6 +118,9 @@ export async function akmImprove(options = {}) {
     // The usage sink resolves it per append.
     let eventsCtx = { dbPath: resolvedStateDbPath };
     let disposeLlmUsageSink = () => { };
+    // Every terminal LLM record this run's own sink sees, in call order. The
+    // usage report is built from these, not from a wall-clock read of state.db.
+    const usageRecords = [];
     const releaseRunLock = () => {
         const ownership = improveLockOwnership;
         if (!ownership)
@@ -164,7 +167,8 @@ export async function akmImprove(options = {}) {
                 return buildLockSkippedResult(selectedStrategy.name, scope, options.runId);
             }
             improveLockOwnership = acquisition.ownership;
-            disposeLlmUsageSink = installLlmUsagePersistence(() => eventsCtx, () => {
+            disposeLlmUsageSink = installLlmUsagePersistence(() => eventsCtx, (record) => {
+                usageRecords.push(record);
                 firstEngineResponseSeen = true;
                 clearFirstResponseHeartbeat();
             });
@@ -227,7 +231,15 @@ export async function akmImprove(options = {}) {
             clearFirstResponseHeartbeat = () => clearTimeout(firstResponseTimer);
         }
         const seq = await runImproveStageSequence(setup, collected, preEnsureCleanupWarnings, eventsCtx);
-        const result = finalizeImproveResult({ run: setup, seq, collected, triageDrain, ensureIndexDurationMs, eventsCtx });
+        const result = finalizeImproveResult({
+            run: setup,
+            seq,
+            collected,
+            triageDrain,
+            ensureIndexDurationMs,
+            eventsCtx,
+            usageRecords,
+        });
         // The run's write provenance goes on the envelope before the sync, so
         // `writtenPaths` is exactly the set the commit is scoped to.
         const writtenPaths = describeRunWrittenPaths(setup, journal?.writtenPaths() ?? []);
@@ -843,7 +855,7 @@ async function runImproveStageSequence(run, collected, preEnsureCleanupWarnings,
 }
 /** Assemble the result envelope and emit `improve_completed`. */
 function finalizeImproveResult(args) {
-    const { run, collected, triageDrain, ensureIndexDurationMs, eventsCtx } = args;
+    const { run, collected, triageDrain, ensureIndexDurationMs, eventsCtx, usageRecords } = args;
     const { preparation, postLoop, reflectsWithErrorContext, finalActions } = args.seq;
     const { options, startMs, resolvedPlan } = run;
     const { memoryCleanupPlan, strategyFilteredRefs } = collected;
@@ -852,12 +864,12 @@ function finalizeImproveResult(args) {
     const { memoryInferenceDurationMs } = postLoop;
     // The per-ref distill-skipped rows fold into a bounded aggregate before persistence (C1).
     const { actions: persistedActions, aggregate: distillSkippedAggregate } = foldDistillSkipped(finalActions);
-    // This run's LLM accounting (#944): llm_usage rows carry no run id, so the
-    // read is bounded by the run's own wall clock.
-    const usageEvents = readEvents({ since: new Date(startMs).toISOString(), type: LLM_USAGE_EVENT }, eventsCtx).events;
+    // This run's LLM accounting (#944): built from the records this run's own
+    // sink collected, so calls other akm processes persist to state.db while
+    // the run is in flight (llm_usage rows carry no run id) never count here.
     const usageReport = buildImproveUsageReport({
         resolvedPlan,
-        byProcessEngineModel: summarizeLlmUsageCrossTab(usageEvents),
+        byProcessEngineModel: summarizeLlmUsageRecordsCrossTab(usageRecords),
         strategyFilteredRefsCount: strategyFilteredRefs.length,
         loopRefs: preparation.loopRefs,
         persistedActions,