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

package/dist/llm/usage-persist.js

@@ -20,7 +20,7 @@
  * swallowing in `emitLlmUsage`, telemetry can never break a real run.
  */
 import { appendEvent } from "../core/events.js";
-import { clearLlmUsageSink, hasLlmUsageSink, setLlmUsageSink } from "./usage-telemetry.js";
+import { clearLlmUsageSink, getLlmUsageSink, hasLlmUsageSink, setLlmUsageSink, } from "./usage-telemetry.js";
 /** Event type for persisted per-call LLM usage telemetry. */
 export const LLM_USAGE_EVENT = "llm_usage";
 /** Event type for the owning sink's terminal-record count marker. */
@@ -59,9 +59,12 @@ function toEventMetadata(record) {
 }
 /**
  * Install a usage sink that persists each LLM call as an `llm_usage` event via
- * `appendEvent`. Returns a disposer that clears the sink — call it in a
- * `finally` block so per-run wiring does not leak across runs (and so the
- * test-isolation harness sees a clean sink between tests).
+ * `appendEvent`. Returns a disposer that restores the sink that was installed
+ * before this one (clearing it when there was none) — call it in a `finally`
+ * block so per-run wiring does not leak across runs (and so the test-isolation
+ * harness sees a clean sink between tests). Restoring rather than clearing lets
+ * a per-run sink (`akm improve`) sit on top of the process-wide one `runCli`
+ * installs, which then resumes when the run ends.
  *
  * `ctx` should carry the same long-lived `state.db` handle the caller already
  * opened for its other events. A getter is resolved for every append so a
@@ -73,9 +76,10 @@ function toEventMetadata(record) {
  * it to know the run is no longer silent, without this module taking on any
  * dependency of its own on improve's lifecycle.
  */
-export function installLlmUsagePersistence(ctx, onRecord) {
+export function installLlmUsagePersistence(ctx, onRecord, options = {}) {
     let expectedTerminalRecords = 0;
     let disposed = false;
+    const previous = getLlmUsageSink();
     setLlmUsageSink((record) => {
         expectedTerminalRecords += 1;
         onRecord?.(record);
@@ -85,7 +89,12 @@ export function installLlmUsagePersistence(ctx, onRecord) {
         if (disposed)
             return;
         disposed = true;
-        clearLlmUsageSink();
+        if (previous)
+            setLlmUsageSink(previous);
+        else
+            clearLlmUsageSink();
+        if (options.skipEmptySummary && expectedTerminalRecords === 0)
+            return;
         try {
             appendEvent({ eventType: LLM_USAGE_SUMMARY_EVENT, metadata: { expectedTerminalRecords } }, typeof ctx === "function" ? ctx() : ctx);
         }
@@ -96,13 +105,15 @@ export function installLlmUsagePersistence(ctx, onRecord) {
 }
 /**
  * Like {@link installLlmUsagePersistence}, but a no-op when a sink is already
- * installed — used by standalone entry points (`akm proposal drain`)
- * that may also run as a sub-step of `akm improve`. When invoked inside an
- * enclosing run the existing per-run sink keeps ownership; the returned
- * disposer then does nothing, so the enclosing run's `finally` still clears it.
+ * installed — used by `runCli` for the process-wide sink and by standalone
+ * entry points (`akm proposal drain`) that may also run as a sub-step of
+ * `akm improve`. When invoked inside an enclosing run the existing sink keeps
+ * ownership; the returned disposer then does nothing. A sink installed here
+ * writes no summary marker when it saw no call, so commands that never reach an
+ * LLM leave no event behind.
  */
 export function installLlmUsagePersistenceIfAbsent(ctx) {
     if (hasLlmUsageSink())
         return () => { };
-    return installLlmUsagePersistence(ctx);
+    return installLlmUsagePersistence(ctx, undefined, { skipEmptySummary: true });
 }

package/dist/llm/usage-telemetry.js

@@ -49,6 +49,10 @@ export function currentLlmStage() {
 export function setLlmUsageSink(sink) {
     usageSink = sink;
 }
+/** The currently installed sink, or `undefined` when none is. Lets an owner restore it after installing its own. */
+export function getLlmUsageSink() {
+    return usageSink;
+}
 /** Remove the installed sink so subsequent calls emit nowhere. Idempotent. */
 export function clearLlmUsageSink() {
     usageSink = undefined;

package/dist/output/html-render.js

@@ -5,18 +5,19 @@
  * `--format html` rendering primitives (#582).
  *
  * Templates live in `src/assets/templates/html/` (mirrored to
- * `dist/assets/templates/html/` by `scripts/copy-assets.ts`). `akm health` is
- * the only command with a bespoke `<command>.html` template (substituted here
- * via plain `%%TOKEN%%` string replacement — no template engine, by design);
- * `src/cli/shared.ts`'s `output()` calls it directly for `command === "health"`
- * and every other command falls back to `renderGenericHtml` (`./generic-render`).
- * `--format html` therefore works for every command (D7) — this module's
- * template path is just health's opt-in bespoke rendering, not a format-wide
- * gate.
+ * `dist/assets/templates/html/` by `scripts/copy-assets.ts`). `akm health` and
+ * `akm metrics` are the only commands with a bespoke `<command>.html` template
+ * (substituted here via plain `%%TOKEN%%` string replacement — no template
+ * engine, by design); `src/cli/shared.ts`'s `output()` calls their renderers
+ * directly and every other command falls back to `renderGenericHtml`
+ * (`./generic-render`). `--format html` therefore works for every command (D7)
+ * — this module's template path is just the opt-in bespoke rendering, not a
+ * format-wide gate.
  */
 import fs from "node:fs";
 import path from "node:path";
 import healthTemplate from "../assets/templates/html/health.html" with { type: "text" };
+import metricsTemplate from "../assets/templates/html/metrics.html" with { type: "text" };
 import { getDirname } from "../runtime.js";
 import { writeStdout } from "./stdout.js";
 const TEMPLATES_DIR = path.join(getDirname(import.meta.url), "../assets/templates/html");
@@ -38,6 +39,7 @@ const EMBEDDED_TEMPLATES = {
     // the file's contents as a string on every runtime. The cast reconciles the
     // ambient declaration with the actual import attribute.
     health: healthTemplate,
+    metrics: metricsTemplate,
 };
 /**
  * Resolve the on-disk template path for a command's bespoke `<command>.html`.
@@ -97,6 +99,11 @@ export function escapeHtml(value) {
         .replaceAll('"', "&quot;")
         .replaceAll("'", "&#39;");
 }
+/** Emit a <time> element that the browser's JS will reformat to the viewer's local timezone. */
+export function isoTimeTag(iso) {
+    const fallback = iso.slice(0, 16).replace("T", " ");
+    return `<time data-iso="${escapeHtml(iso)}">${escapeHtml(fallback)}</time>`;
+}
 /**
  * Deliver a rendered document: write to `outputPath` when set (`--output`),
  * otherwise print to stdout.

package/dist/output/shapes/passthrough.js

@@ -50,6 +50,7 @@ const PASSTHROUGH_COMMANDS = [
     "info",
     "lint",
     "list",
+    "metrics",
     "models",
     "proposal-accept-batch",
     "proposal-drain",

package/dist/output/text/metrics.js

@@ -0,0 +1,39 @@
+// 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/.
+/**
+ * `akm metrics --format text`: aligned sections with top-N tables. Lists are
+ * cut to 5 at `--detail brief` and show everything the top-20 cap kept otherwise.
+ */
+import { buildMetricsView, isMetricsResult } from "../../commands/metrics/report-view.js";
+const flat = (s) => s.replace(/\s*\r?\n\s*/g, " ");
+function renderTable(table) {
+    const all = [table.headers, ...table.rows].map((r) => r.map(flat));
+    const widths = table.headers.map((_, i) => Math.max(...all.map((r) => (r[i] ?? "").length)));
+    const line = (r) => `  ${r.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")}`.trimEnd();
+    return [`${table.title}:`, ...all.map(line)];
+}
+export function formatMetricsPlain(result, detail) {
+    if (!isMetricsResult(result))
+        return null;
+    const view = buildMetricsView(result, detail);
+    const lines = [`akm metrics  ${view.window}`, `filters: ${view.filters}`];
+    for (const section of view.sections) {
+        lines.push("", section.title.toUpperCase());
+        const labelWidth = Math.max(0, ...section.facts.map(([label]) => label.length));
+        for (const [label, value] of section.facts)
+            lines.push(`  ${label.padEnd(labelWidth)}  ${value}`);
+        for (const table of section.tables) {
+            if (table.rows.length > 0)
+                lines.push("", ...renderTable(table));
+            else if (!table.hideWhenEmpty)
+                lines.push("", `${table.title}: (none)`);
+        }
+    }
+    if (view.notes.length > 0)
+        lines.push("", "NOTES", ...view.notes.map((n) => `  - ${flat(n)}`));
+    return lines.join("\n");
+}
+export const metricsFormatters = [
+    { command: "metrics", handler: (r, detail) => formatMetricsPlain(r, detail) },
+];

package/dist/output/text.js

@@ -19,6 +19,7 @@ import { indexFormatters } from "./text/index.js";
 import { infoFormatters } from "./text/info.js";
 import { lintFormatters } from "./text/lint.js";
 import { listFormatters } from "./text/list.js";
+import { metricsFormatters } from "./text/metrics.js";
 import { migrateFormatters } from "./text/migrate.js";
 import { modelsFormatters } from "./text/models.js";
 import { proposalProducerFormatters } from "./text/proposal/producer.js";
@@ -59,6 +60,7 @@ const BUILT_IN_TEXT_FORMATTERS = [
     ...proposalProducerFormatters,
     ...infoFormatters,
     ...healthFormatters,
+    ...metricsFormatters,
     ...improveReportFormatters,
     ...lintFormatters,
     ...configFormatters,

package/dist/scripts/akm-migrate-node.js

@@ -28449,6 +28449,243 @@ registerMdRenderer("health", (result) => {
   return null;
 });
 
+// src/commands/metrics/report-view.ts
+var BRIEF_LIST_LIMIT = 5;
+function isMetricsResult(value) {
+  if (value === null || typeof value !== "object")
+    return false;
+  const r = value;
+  return r.schemaVersion === 1 && !!r.window && !!r.usage && !!r.feedback && !!r.llm;
+}
+var int = (n) => String(n);
+var dash = (v) => v === undefined || v === "" ? "-" : v;
+var pct = (n) => n === null ? "n/a" : `${(n * 100).toFixed(1)}%`;
+var ms = (n) => n === null ? "n/a" : `${Math.round(n)} ms`;
+var fixed = (n, digits) => n === null ? "n/a" : n.toFixed(digits);
+function sourceFacts(counts) {
+  const entries = Object.entries(counts);
+  return entries.length === 0 ? "-" : entries.map(([k, v]) => `${k}=${v}`).join(" ");
+}
+function llmRows(group) {
+  return Object.entries(group).map(([name, a]) => [
+    name,
+    int(a.calls),
+    int(a.failures),
+    int(a.promptTokens),
+    int(a.completionTokens),
+    int(a.totalTokens),
+    ms(a.totalDurationMs)
+  ]);
+}
+var LLM_HEADERS = ["name", "calls", "failed", "prompt", "completion", "total", "time"];
+function buildMetricsView(r, detail) {
+  const brief = detail === "brief";
+  const cut = (items) => brief ? items.slice(0, BRIEF_LIST_LIMIT) : items;
+  const { usage, feedback, utility, llm } = r;
+  const searches = usage.totals.searches;
+  const sections = [
+    {
+      title: "Usage",
+      facts: [
+        ["searches", int(searches)],
+        ["shows", int(usage.totals.shows)],
+        ["curates", int(usage.totals.curates)],
+        ["selects", int(usage.totals.selects)],
+        ["select rate", pct(usage.selectRate)],
+        [
+          "zero-result searches",
+          `${usage.totals.zeroResultSearches} (${pct(searches === 0 ? null : usage.totals.zeroResultSearches / searches)})`
+        ],
+        ["search median", ms(usage.searchMedianMs)],
+        ["distinct assets", int(usage.totals.distinctAssets)],
+        ["distinct queries", int(usage.totals.distinctQueries)],
+        ["by source", sourceFacts(usage.bySource)]
+      ],
+      tables: [
+        {
+          title: "Top assets",
+          headers: ["ref", "shows", "search hits", "selects", "+", "-", "last used"],
+          rows: cut(usage.topAssets).map((a) => [
+            a.ref,
+            int(a.shows),
+            int(a.searchHits),
+            int(a.selects),
+            int(a.positive),
+            int(a.negative),
+            dash(a.lastUsedAt)
+          ])
+        },
+        {
+          title: "Top queries",
+          headers: ["query", "count", "avg results", "last"],
+          rows: cut(usage.topQueries).map((q) => [q.query, int(q.count), fixed(q.avgResults, 1), q.lastAt])
+        },
+        {
+          title: "Zero-result queries",
+          headers: ["query", "count", "last"],
+          rows: cut(usage.zeroResultQueries).map((q) => [q.query, int(q.count), q.lastAt])
+        },
+        {
+          title: "Daily",
+          headers: ["day", "search", "show", "curate", "feedback"],
+          rows: brief ? [] : usage.daily.map((d) => [d.day, int(d.search), int(d.show), int(d.curate), int(d.feedback)]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "Feedback",
+      facts: [
+        ["positive", int(feedback.totals.positive)],
+        ["negative", int(feedback.totals.negative)]
+      ],
+      tables: [
+        {
+          title: "By asset",
+          headers: ["ref", "+", "-", "valence", "last"],
+          rows: cut(feedback.byAsset).map((a) => [
+            a.ref,
+            int(a.positive),
+            int(a.negative),
+            fixed(a.valence, 2),
+            a.lastAt
+          ])
+        },
+        {
+          title: "By tag",
+          headers: ["tag", "+", "-"],
+          rows: cut(Object.entries(feedback.byTag)).map(([tag, c]) => [tag, int(c.positive), int(c.negative)]),
+          hideWhenEmpty: true
+        },
+        {
+          title: "Recent negative",
+          headers: ["ref", "at", "reason", "tags"],
+          rows: cut(feedback.recentNegative).map((n) => [n.ref, n.at, dash(n.reason), dash(n.tags?.join(", "))])
+        }
+      ]
+    },
+    {
+      title: "Utility",
+      facts: [
+        ["scored assets", int(utility.count)],
+        ["never used", int(utility.neverUsed)]
+      ],
+      tables: [
+        {
+          title: "Histogram",
+          headers: ["bucket", "count"],
+          rows: utility.histogram.map((h) => [h.bucket, int(h.count)]),
+          hideWhenEmpty: true
+        },
+        { title: "Lowest", headers: utilityHeaders(), rows: cut(utility.lowest).map(utilityRow) },
+        { title: "Highest", headers: utilityHeaders(), rows: cut(utility.highest).map(utilityRow) },
+        {
+          title: "Lowest outcome",
+          headers: ["ref", "outcome", "retrievals", "negative", "accepted changes"],
+          rows: cut(r.outcomes.lowestOutcome).map((o) => [
+            o.ref,
+            fixed(o.outcomeScore, 2),
+            int(o.retrievalCount),
+            int(o.negativeFeedbackCount),
+            int(o.acceptedChangeCount)
+          ]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "LLM",
+      facts: [
+        ["calls", int(llm.calls)],
+        ["failed", int(llm.failures)],
+        ["prompt tokens", int(llm.promptTokens)],
+        ["completion tokens", int(llm.completionTokens)],
+        ["reasoning tokens", int(llm.reasoningTokens)],
+        ["total tokens", int(llm.totalTokens)],
+        ["time", ms(llm.totalDurationMs)]
+      ],
+      tables: [
+        { title: "By engine", headers: LLM_HEADERS, rows: cut(llmRows(llm.byEngine)), hideWhenEmpty: true },
+        { title: "By process", headers: LLM_HEADERS, rows: cut(llmRows(llm.byProcess)), hideWhenEmpty: true },
+        { title: "By stage", headers: LLM_HEADERS, rows: cut(llmRows(llm.byStage)), hideWhenEmpty: true }
+      ]
+    },
+    {
+      title: "Index",
+      facts: [
+        ["runs", int(r.index.runs)],
+        ["median time", ms(r.index.medianMs)]
+      ],
+      tables: [
+        {
+          title: "Recent runs",
+          headers: ["at", "mode", "time"],
+          rows: brief ? [] : r.index.recent.map((i) => [i.at, i.mode, ms(i.totalMs)]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "Tasks",
+      facts: [
+        ["runs", int(r.tasks.runs)],
+        ["failed", int(r.tasks.failed)],
+        ["fail rate", pct(r.tasks.failRate)]
+      ],
+      tables: [
+        {
+          title: "By task",
+          headers: ["task", "runs", "failed", "median"],
+          rows: cut(r.tasks.byTask).map((t) => [t.taskId, int(t.runs), int(t.failed), ms(t.medianMs)]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "Proposals",
+      facts: [["by status", sourceFacts(r.proposals.byStatus)]],
+      tables: [
+        {
+          title: "Accept rate by source",
+          headers: ["source", "total", "accepted", "rejected", "pending", "accept rate"],
+          rows: r.proposals.acceptRateBySource.map((p) => [
+            p.source,
+            int(p.total),
+            int(p.accepted),
+            int(p.rejected),
+            int(p.pending),
+            pct(p.acceptRate)
+          ]),
+          hideWhenEmpty: true
+        }
+      ]
+    },
+    {
+      title: "Workflows",
+      facts: [
+        ["runs", int(r.workflows.runs)],
+        ["by status", sourceFacts(r.workflows.byStatus)],
+        ["tokens", int(r.workflows.tokens)],
+        ["tokens by model", sourceFacts(r.workflows.byModel)]
+      ],
+      tables: []
+    }
+  ];
+  const f = r.filters;
+  return {
+    window: `${r.window.since} to ${r.window.until}`,
+    filters: `source=${f.source}`,
+    sections,
+    notes: r.notes
+  };
+}
+function utilityHeaders() {
+  return ["ref", "utility", "shows", "searches", "select rate", "last used"];
+}
+function utilityRow(u) {
+  return [u.ref, fixed(u.utility, 2), int(u.showCount), int(u.searchCount), pct(u.selectRate), dash(u.lastUsedAt)];
+}
+
 // src/output/generic-render.ts
 var ENVELOPE_META_KEYS = new Set(["shape", "schemaVersion"]);
 function flattenForText(value, path11, lines) {
@@ -29049,6 +29286,7 @@ var PASSTHROUGH_COMMANDS = [
   "info",
   "lint",
   "list",
+  "metrics",
   "models",
   "proposal-accept-batch",
   "proposal-drain",
@@ -30323,10 +30561,10 @@ function formatHealthPlain(r, detail) {
 `).trim();
 }
 // src/output/text/lint-format.ts
-function glyphFor(fixed) {
-  if (fixed === "failed")
+function glyphFor(fixed2) {
+  if (fixed2 === "failed")
     return { glyph: "✗", severityRank: 0 };
-  if (fixed === true)
+  if (fixed2 === true)
     return { glyph: "✓", severityRank: 2 };
   return { glyph: "⚠", severityRank: 1 };
 }
@@ -30345,17 +30583,17 @@ function renderIssueSection(title, issues) {
 function formatLintPlain(r) {
   if (r === null || typeof r !== "object")
     return null;
-  const fixed = Array.isArray(r.fixed) ? r.fixed : [];
+  const fixed2 = Array.isArray(r.fixed) ? r.fixed : [];
   const flagged = Array.isArray(r.flagged) ? r.flagged : [];
   const warnings = Array.isArray(r.warnings) ? r.warnings : [];
   const summary = r.summary;
   const lines = [];
   if (typeof r.ok === "boolean")
     lines.push(`ok: ${r.ok}`);
-  lines.push(`summary: fixed=${summary?.fixed ?? fixed.length} flagged=${summary?.flagged ?? flagged.length}` + ` warnings=${summary?.warnings ?? warnings.length}`);
+  lines.push(`summary: fixed=${summary?.fixed ?? fixed2.length} flagged=${summary?.flagged ?? flagged.length}` + ` warnings=${summary?.warnings ?? warnings.length}`);
   lines.push("", ...renderIssueSection("flagged", flagged));
   lines.push("", ...renderIssueSection("warnings", warnings));
-  lines.push("", ...renderIssueSection("fixed", fixed));
+  lines.push("", ...renderIssueSection("fixed", fixed2));
   return lines.join(`
 `).trim();
 }
@@ -36816,8 +37054,8 @@ function getConfigLockPath() {
 }
 var CONFIG_LOCK_MAX_RETRIES = 40;
 var CONFIG_LOCK_RETRY_DELAY_MS = 50;
-function sleepSyncMs(ms) {
-  sleepSync(ms);
+function sleepSyncMs(ms2) {
+  sleepSync(ms2);
 }
 function acquireConfigLock() {
   const lockPath = getConfigLockPath();
@@ -53175,6 +53413,40 @@ var lintFormatters = [{ command: "lint", handler: (r) => formatLintPlain(r) }];
 // src/output/text/list.ts
 var listFormatters = [{ command: "list", handler: (r) => formatListPlain(r) }];
 
+// src/output/text/metrics.ts
+var flat = (s) => s.replace(/\s*\r?\n\s*/g, " ");
+function renderTable2(table) {
+  const all = [table.headers, ...table.rows].map((r) => r.map(flat));
+  const widths = table.headers.map((_, i) => Math.max(...all.map((r) => (r[i] ?? "").length)));
+  const line = (r) => `  ${r.map((c, i) => c.padEnd(widths[i] ?? 0)).join("  ")}`.trimEnd();
+  return [`${table.title}:`, ...all.map(line)];
+}
+function formatMetricsPlain(result, detail) {
+  if (!isMetricsResult(result))
+    return null;
+  const view = buildMetricsView(result, detail);
+  const lines = [`akm metrics  ${view.window}`, `filters: ${view.filters}`];
+  for (const section of view.sections) {
+    lines.push("", section.title.toUpperCase());
+    const labelWidth = Math.max(0, ...section.facts.map(([label]) => label.length));
+    for (const [label, value] of section.facts)
+      lines.push(`  ${label.padEnd(labelWidth)}  ${value}`);
+    for (const table of section.tables) {
+      if (table.rows.length > 0)
+        lines.push("", ...renderTable2(table));
+      else if (!table.hideWhenEmpty)
+        lines.push("", `${table.title}: (none)`);
+    }
+  }
+  if (view.notes.length > 0)
+    lines.push("", "NOTES", ...view.notes.map((n) => `  - ${flat(n)}`));
+  return lines.join(`
+`);
+}
+var metricsFormatters = [
+  { command: "metrics", handler: (r, detail) => formatMetricsPlain(r, detail) }
+];
+
 // src/output/text/migrate.ts
 function planGlyph(status) {
   switch (status) {
@@ -53309,6 +53581,7 @@ var BUILT_IN_TEXT_FORMATTERS = [
   ...proposalProducerFormatters,
   ...infoFormatters,
   ...healthFormatters,
+  ...metricsFormatters,
   ...improveReportFormatters,
   ...lintFormatters,
   ...configFormatters,