akm-cli 0.9.0-beta.1 → 0.9.0-beta.10

package/dist/llm/usage-persist.js

@@ -0,0 +1,77 @@
+// 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/.
+/**
+ * Bridge per-call LLM usage telemetry (#576) to the events stream.
+ *
+ * `usage-telemetry.ts` stays dependency-free of the events/db layer so the
+ * low-level `client.ts` never imports persistence. This module is the wiring:
+ * it installs a {@link LlmUsageSink} that persists each {@link LlmUsageRecord}
+ * as one `llm_usage` event.
+ *
+ * Why reuse the events table (vs a dedicated table): volume is low (~100
+ * calls/day), the records are append-only and time-windowed exactly like every
+ * other event, and `akm health` already aggregates per-window event reads — a
+ * separate table would duplicate retention (`purgeOldEvents`), reads, and
+ * migration surface for no benefit. See the commit message for #576.
+ *
+ * Every record is written through `appendEvent`, which is itself best-effort
+ * (a write failure logs once and never throws). Combined with the sink-error
+ * swallowing in `emitLlmUsage`, telemetry can never break a real run.
+ */
+import { appendEvent } from "../core/events.js";
+import { clearLlmUsageSink, hasLlmUsageSink, setLlmUsageSink } from "./usage-telemetry.js";
+/** Event type for persisted per-call LLM usage telemetry. */
+export const LLM_USAGE_EVENT = "llm_usage";
+/**
+ * Project a usage record into event metadata, dropping `undefined` token
+ * fields so an absent-usage call records only `{stage, model, durationMs}`.
+ */
+function toEventMetadata(record) {
+    const metadata = { durationMs: record.durationMs };
+    if (record.stage !== undefined)
+        metadata.stage = record.stage;
+    if (record.model !== undefined)
+        metadata.model = record.model;
+    if (record.finishReason !== undefined)
+        metadata.finishReason = record.finishReason;
+    if (record.promptTokens !== undefined)
+        metadata.promptTokens = record.promptTokens;
+    if (record.completionTokens !== undefined)
+        metadata.completionTokens = record.completionTokens;
+    if (record.totalTokens !== undefined)
+        metadata.totalTokens = record.totalTokens;
+    if (record.reasoningTokens !== undefined)
+        metadata.reasoningTokens = record.reasoningTokens;
+    return metadata;
+}
+/**
+ * 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).
+ *
+ * `ctx` should carry the same long-lived `state.db` handle the caller already
+ * opened for its other events; when omitted, `appendEvent` falls back to its
+ * default open-insert-close path.
+ */
+export function installLlmUsagePersistence(ctx) {
+    setLlmUsageSink((record) => {
+        appendEvent({ eventType: LLM_USAGE_EVENT, metadata: toEventMetadata(record) }, ctx);
+    });
+    return () => {
+        clearLlmUsageSink();
+    };
+}
+/**
+ * Like {@link installLlmUsagePersistence}, but a no-op when a sink is already
+ * installed — used by standalone entry points (`akm consolidate`, `akm 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.
+ */
+export function installLlmUsagePersistenceIfAbsent(ctx) {
+    if (hasLlmUsageSink())
+        return () => { };
+    return installLlmUsagePersistence(ctx);
+}

package/dist/llm/usage-telemetry.js

@@ -0,0 +1,103 @@
+// 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/.
+/**
+ * Per-call LLM usage telemetry (#576).
+ *
+ * `chatCompletion` captures usage + model + finish_reason + wall-time for
+ * EVERY OpenAI-compatible call and emits one {@link LlmUsageRecord} through a
+ * module-level sink. The sink indirection keeps `client.ts` free of any
+ * dependency on the events/db layer: the application wires the sink to
+ * persistence at startup / per improve run, and tests can inspect records in
+ * memory.
+ *
+ * The pipeline *stage* that made the call is ambient, not threaded through
+ * call sites. A param-threading prototype was deliberately discarded in 0.8.5
+ * (every call site would have to forward a `stage` argument it does not care
+ * about). Instead callers wrap a well-delimited phase once with
+ * {@link withLlmStage}; any `chatCompletion` invoked inside that async region —
+ * however deeply nested — is attributed to that stage via `AsyncLocalStorage`.
+ *
+ * EVERYTHING here is best-effort. Telemetry must NEVER break a real LLM call:
+ * a sink that throws, an unset stage, or a malformed usage block all degrade
+ * silently. `emitLlmUsage` swallows sink errors; `currentLlmStage` returns
+ * `undefined` outside any `withLlmStage` scope.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const stageStorage = new AsyncLocalStorage();
+let usageSink;
+/**
+ * Run `fn` with `stage` as the ambient LLM stage. Any `chatCompletion` call
+ * made synchronously or asynchronously within `fn` (including through awaited
+ * helpers and nested `withLlmStage` calls — the innermost wins) is attributed
+ * to `stage`. Returns whatever `fn` returns; never alters control flow.
+ */
+export function withLlmStage(stage, fn) {
+    return stageStorage.run(stage, fn);
+}
+/** The ambient LLM stage for the current async context, or `undefined` outside any {@link withLlmStage} scope. */
+export function currentLlmStage() {
+    return stageStorage.getStore();
+}
+/**
+ * Install the process-wide usage sink. Replaces any previously installed sink.
+ * The application wires this to persistence; tests install an in-memory
+ * collector. Pair with {@link clearLlmUsageSink} in a `finally` block.
+ */
+export function setLlmUsageSink(sink) {
+    usageSink = sink;
+}
+/** Remove the installed sink so subsequent calls emit nowhere. Idempotent. */
+export function clearLlmUsageSink() {
+    usageSink = undefined;
+}
+/**
+ * Whether a usage sink is currently installed. Standalone entry points use
+ * this to avoid clobbering a sink an enclosing run (e.g. `akm improve`) already
+ * installed: they install their own only when none is active.
+ */
+export function hasLlmUsageSink() {
+    return usageSink !== undefined;
+}
+/**
+ * Emit one usage record to the installed sink, stamping the ambient stage.
+ * Best-effort: no sink is a no-op, and a sink that throws is swallowed so
+ * telemetry can never fail the LLM call that produced it.
+ */
+export function emitLlmUsage(record) {
+    const sink = usageSink;
+    if (!sink)
+        return;
+    try {
+        sink({ ...record, stage: record.stage ?? currentLlmStage() });
+    }
+    catch {
+        // Telemetry must never break a real run.
+    }
+}
+function asFiniteNonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/**
+ * Project a provider `usage` block into the token fields of an
+ * {@link LlmUsageRecord}. Missing or garbled values are omitted (not zeroed)
+ * so a best-effort record still distinguishes "0 tokens" from "unknown".
+ */
+export function extractUsageTokens(usage) {
+    if (!usage || typeof usage !== "object")
+        return {};
+    const out = {};
+    const prompt = asFiniteNonNegative(usage.prompt_tokens);
+    const completion = asFiniteNonNegative(usage.completion_tokens);
+    const total = asFiniteNonNegative(usage.total_tokens);
+    const reasoning = asFiniteNonNegative(usage.completion_tokens_details?.reasoning_tokens);
+    if (prompt !== undefined)
+        out.promptTokens = prompt;
+    if (completion !== undefined)
+        out.completionTokens = completion;
+    if (total !== undefined)
+        out.totalTokens = total;
+    if (reasoning !== undefined)
+        out.reasoningTokens = reasoning;
+    return out;
+}

package/dist/output/context.js

@@ -12,7 +12,7 @@
  * Initialized from `cli.ts` before `runMain`.
  */
 import { UsageError } from "../core/errors.js";
-export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md"];
+export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md", "html"];
 export const DETAIL_LEVELS = ["brief", "normal", "full"];
 export const SHAPE_MODES = ["human", "agent", "summary"];
 export function parseOutputFormat(value) {
@@ -80,7 +80,8 @@ export function resolveOutputMode(argv, defaults = {}) {
     // use `--shape`. Unknown `--detail` values fall through to the default.
     const detail = parseDetailLevel(rawDetail) ?? defaults?.detail ?? "brief";
     const shape = parseShapeMode(rawShape) ?? "human";
-    return { format, detail, shape, forAgent: shape === "agent" };
+    const outputPath = parseFlagValue(argv, "--output");
+    return { format, detail, shape, forAgent: shape === "agent", ...(outputPath ? { outputPath } : {}) };
 }
 let _mode;
 /**

package/dist/output/html-render.js

@@ -0,0 +1,73 @@
+// 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/.
+/**
+ * `--format html` rendering primitives (#582).
+ *
+ * Templates live in `src/assets/templates/html/` (mirrored to
+ * `dist/assets/templates/html/` by `scripts/copy-assets.ts`). A command with a
+ * bespoke template ships `<command>.html`; every other command falls back to
+ * `default.html`, which renders the command's JSON envelope in a `<pre>`
+ * block. Substitution is plain `%%TOKEN%%` string replacement — no template
+ * engine, by design.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getDirname } from "../runtime.js";
+const TEMPLATES_DIR = path.join(getDirname(import.meta.url), "../assets/templates/html");
+/** Template used by every command without a bespoke `<command>.html`. */
+export const DEFAULT_TEMPLATE = "default";
+/**
+ * Resolve the on-disk template path for a command. `<command>.html` when the
+ * command ships a bespoke template (today: `health`), otherwise
+ * `default.html`. Command names are sanitized to a bare basename so a hostile
+ * command string can never escape the templates directory.
+ */
+export function resolveTemplatePath(command) {
+    const name = path.basename(command.trim());
+    const candidate = path.join(TEMPLATES_DIR, `${name}.html`);
+    if (name !== DEFAULT_TEMPLATE && fs.existsSync(candidate))
+        return candidate;
+    return path.join(TEMPLATES_DIR, `${DEFAULT_TEMPLATE}.html`);
+}
+/** Matches a `%%TOKEN%%` placeholder (uppercase + underscore key). */
+const TOKEN_RE = /%%[A-Z_]+%%/g;
+/**
+ * Read a template and substitute every `%%TOKEN%%` in `replacements` in a
+ * single pass. Substitution is order-independent: a value that happens to
+ * contain another token's literal text is never re-processed (the pass scans
+ * the original template, not the growing output). Unknown tokens in the
+ * template are left in place (the health template is verified token-complete by
+ * tests); replacement keys missing from the template are silently ignored,
+ * matching the skill renderer's behaviour.
+ */
+export function renderHtml(templatePath, replacements) {
+    const html = fs.readFileSync(templatePath, "utf8");
+    return html.replace(TOKEN_RE, (token) => (token in replacements ? replacements[token] : token));
+}
+/**
+ * Minimal HTML entity escaping for text interpolated into templates. Escapes
+ * the single quote as well as the double quote so escaped values are safe in
+ * both `"…"` and `'…'` attribute contexts, not only the double-quoted
+ * attributes the bundled templates use today.
+ */
+export function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+/**
+ * Deliver a rendered document: write to `outputPath` when set (`--output`),
+ * otherwise print to stdout.
+ */
+export function deliverRendered(content, outputPath) {
+    if (outputPath) {
+        fs.mkdirSync(path.dirname(path.resolve(outputPath)), { recursive: true });
+        fs.writeFileSync(outputPath, content.endsWith("\n") ? content : `${content}\n`);
+        return;
+    }
+    console.log(content);
+}

package/dist/output/shapes/helpers.js

@@ -41,7 +41,21 @@ export function shapeProposalEntry(entry, detail) {
         return pickFields(entry, ["id", "ref", "status", "source", "createdAt"]);
     }
     if (detail === "normal") {
-        return pickFields(entry, ["id", "ref", "status", "source", "sourceRun", "createdAt", "updatedAt", "review"]);
+        // `confidence` and `gateDecision` (#577) explain why a proposal is pending,
+        // so they are projected at `normal` for `akm proposal list/show` — both are
+        // optional and absent on legacy proposals.
+        return pickFields(entry, [
+            "id",
+            "ref",
+            "status",
+            "source",
+            "sourceRun",
+            "createdAt",
+            "updatedAt",
+            "confidence",
+            "gateDecision",
+            "review",
+        ]);
     }
     // full: project everything including the payload.
     return pickFields(entry, [
@@ -52,6 +66,8 @@ export function shapeProposalEntry(entry, detail) {
         "sourceRun",
         "createdAt",
         "updatedAt",
+        "confidence",
+        "gateDecision",
         "payload",
         "review",
     ]);

package/dist/output/text/helpers.js

@@ -235,6 +235,50 @@ export function formatProposalProducerPlain(command, r) {
     const status = String(proposal.status ?? "pending");
     return `${command}: queued proposal ${id} (${ref}) [${status}]`;
 }
+/**
+ * Render a one-line gate-decision summary for the proposal list / show surfaces
+ * (#577), e.g. `gate=deferred:below-threshold (0.72 < 0.90)`. Returns the empty
+ * string for a missing or malformed decision so legacy proposals render cleanly.
+ */
+export function formatGateDecisionSummary(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return "";
+    const d = raw;
+    const outcome = typeof d.outcome === "string" ? d.outcome : undefined;
+    if (!outcome)
+        return "";
+    const reason = typeof d.reason === "string" && d.reason.length > 0 ? `:${d.reason}` : "";
+    const cmp = formatGateThresholdComparison(d);
+    return `gate=${outcome}${reason}${cmp ? ` (${cmp})` : ""}`;
+}
+/**
+ * Reconstruct the threshold comparison the gate applied, when both sides are
+ * present (e.g. confidence 0.72 vs. autoAccept 0.90 → "0.72 < 0.90"). Returns
+ * the empty string when the decision lacks the operands.
+ */
+function formatGateThresholdComparison(d) {
+    const thresholds = (typeof d.thresholds === "object" && d.thresholds !== null ? d.thresholds : {});
+    const confidence = typeof d.confidence === "number" ? d.confidence : undefined;
+    const autoAccept = typeof thresholds.autoAccept === "number" ? thresholds.autoAccept : undefined;
+    if (confidence !== undefined && autoAccept !== undefined) {
+        const op = confidence >= autoAccept ? ">=" : "<";
+        return `${confidence.toFixed(2)} ${op} ${autoAccept.toFixed(2)}`;
+    }
+    // Drain bands: when the measured value is present, render the full comparison
+    // ("210 > 200" / "1 < 5"); otherwise fall back to the bound alone (#577).
+    const measured = typeof d.measured === "number" ? d.measured : undefined;
+    if (typeof thresholds.maxDiffLines === "number") {
+        return measured !== undefined
+            ? `${measured} > ${thresholds.maxDiffLines}`
+            : `maxDiffLines=${thresholds.maxDiffLines}`;
+    }
+    if (typeof thresholds.minContentLines === "number") {
+        return measured !== undefined
+            ? `${measured} < ${thresholds.minContentLines}`
+            : `minContentLines=${thresholds.minContentLines}`;
+    }
+    return "";
+}
 export function formatProposalListPlain(r) {
     const proposals = Array.isArray(r.proposals) ? r.proposals : [];
     const total = typeof r.totalCount === "number" ? r.totalCount : proposals.length;
@@ -248,7 +292,11 @@ export function formatProposalListPlain(r) {
         const status = String(p.status ?? "?");
         const source = String(p.source ?? "?");
         const created = String(p.createdAt ?? "?");
-        lines.push(`${id}  [${status}] ${ref}  source=${source}  ${created}`);
+        // #577: surface the gate verdict inline so the queue explains itself
+        // ("deferred: below-threshold"). Legacy proposals carry no gateDecision.
+        const gate = formatGateDecisionSummary(p.gateDecision);
+        const gateSuffix = gate ? `  ${gate}` : "";
+        lines.push(`${id}  [${status}] ${ref}  source=${source}  ${created}${gateSuffix}`);
     }
     return lines.join("\n").trimEnd();
 }
@@ -265,6 +313,26 @@ export function formatProposalShowPlain(r) {
         lines.push(`createdAt: ${String(p.createdAt)}`);
     if (p.updatedAt)
         lines.push(`updatedAt: ${String(p.updatedAt)}`);
+    if (typeof p.confidence === "number")
+        lines.push(`confidence: ${p.confidence.toFixed(2)}`);
+    // #577: gate decision (auto-accepted / deferred / auto-rejected + reason +
+    // thresholds). Absent on legacy proposals — render "unknown" so the field is
+    // always present and the operator never sees a silent gap.
+    const gate = p.gateDecision;
+    if (gate && typeof gate.outcome === "string") {
+        lines.push(`gate.decision: ${String(gate.outcome)}`);
+        lines.push(`gate.reason: ${gate.reason ? String(gate.reason) : "unknown"}`);
+        const cmp = formatGateThresholdComparison(gate);
+        if (cmp)
+            lines.push(`gate.thresholds: ${cmp}`);
+        if (gate.gate)
+            lines.push(`gate.by: ${String(gate.gate)}`);
+        if (gate.decidedAt)
+            lines.push(`gate.decidedAt: ${String(gate.decidedAt)}`);
+    }
+    else {
+        lines.push("gate.decision: unknown");
+    }
     const review = p.review;
     if (review) {
         lines.push(`review.outcome: ${String(review.outcome ?? "?")}`);