akm-cli 0.9.0-beta.2 → 0.9.0-beta.27

package/dist/integrations/harnesses/opencode/session-log.js

@@ -26,6 +26,15 @@ export class OpenCodeProvider {
     isAvailable() {
         return fs.existsSync(this.#baseDir);
     }
+    /**
+     * Directory holding opencode's per-project session metadata files
+     * (`<base>/storage/session`). Returns `[]` when it does not exist on this
+     * machine. See {@link SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const sessionRoot = path.join(this.#baseDir, "storage", "session");
+        return fs.existsSync(sessionRoot) ? [sessionRoot] : [];
+    }
     *readEvents(input) {
         // Legacy behavior: stream raw log lines from the top-level dir and `log/`
         // subdirectory. Kept to keep `getExecutionLogCandidates` working without

package/dist/integrations/session-logs/index.js

@@ -28,6 +28,22 @@ const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENO
 export function getAvailableHarnesses() {
     return HARNESSES.filter((harness) => harness.isAvailable());
 }
+/**
+ * Map each available harness to its `{ harnessName, roots }` watch target,
+ * skipping harnesses that expose no roots (absent `watchRoots()` or an empty
+ * result). This is the one stable entry point the watcher uses so it never
+ * reaches into providers directly.
+ */
+export function getWatchTargets() {
+    const targets = [];
+    for (const harness of getAvailableHarnesses()) {
+        const roots = harness.watchRoots?.() ?? [];
+        if (roots.length === 0)
+            continue;
+        targets.push({ harnessName: harness.name, roots });
+    }
+    return targets;
+}
 export function normalizeSessionTopic(text) {
     const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
     if (normalized.length < 10)

package/dist/llm/client.js

@@ -14,6 +14,7 @@ import { fetchWithTimeout } from "../core/common.js";
 import { resolveSecret } from "../core/config/config.js";
 import { escapeJsonStringControls, parseJsonResponse, stripCodeFences, stripThinkBlocks } from "../core/parse.js";
 import { warnVerbose } from "../core/warn.js";
+import { emitLlmUsage, extractUsageTokens } from "./usage-telemetry.js";
 // Re-export shared parse utilities so existing importers of `client.ts` continue
 // to resolve `parseJsonResponse` and `parseEmbeddedJsonResponse` from this module.
 export { escapeJsonStringControls, parseEmbeddedJsonResponse, parseJsonResponse, stripCodeFences, stripThinkBlocks, } from "../core/parse.js";
@@ -118,9 +119,23 @@ function looksLikeContextOverflow(message) {
 /**
  * Decide whether a first-attempt {@link LlmCallError} is eligible for a single
  * retry. Retryable: HTTP 5xx (`provider_error` with statusCode >= 500) and
- * `network_error` whose message looks like a transient connection reset
- * (ECONNRESET / EPIPE / "fetch failed"). NOT retryable: 4xx, `rate_limited`
- * (429), `timeout`, `parse_error`, and context-overflow-classified errors.
+ * `network_error` whose message looks like a transient connection drop.
+ * NOT retryable: 4xx, `rate_limited` (429), `timeout`, `parse_error`, and
+ * context-overflow-classified errors.
+ *
+ * The connection-drop heuristic covers the substrings emitted across runtimes
+ * for a mid-flight socket close:
+ *  - `ECONNRESET` / `EPIPE` — Node/libuv socket reset codes
+ *  - `fetch failed` — undici's generic wrapper message
+ *  - `socket connection was closed` — Bun's message for a dropped connection
+ *    (e.g. "The socket connection was closed unexpectedly.")
+ *  - `terminated` / `other side closed` — undici's phrasings for the same
+ *
+ * These all describe a transient transport failure where a second attempt can
+ * legitimately succeed, which is exactly the case a single bounded retry is
+ * meant to absorb. Before this list was widened, Bun's "socket connection was
+ * closed unexpectedly" fell through unretried and surfaced as a recurring
+ * failure in the improve/reflect and capability-probe flows.
  */
 function isRetryable(err) {
     if (looksLikeContextOverflow(err.message))
@@ -130,7 +145,12 @@ function isRetryable(err) {
     }
     if (err.code === "network_error") {
         const lower = err.message.toLowerCase();
-        return lower.includes("econnreset") || lower.includes("epipe") || lower.includes("fetch failed");
+        return (lower.includes("econnreset") ||
+            lower.includes("epipe") ||
+            lower.includes("fetch failed") ||
+            lower.includes("socket connection was closed") ||
+            lower.includes("terminated") ||
+            lower.includes("other side closed"));
     }
     return false;
 }
@@ -179,6 +199,10 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     const responseFormat = options?.responseSchema && config.supportsJsonSchema
         ? { response_format: { type: "json_schema", json_schema: { schema: options.responseSchema, strict: true } } }
         : {};
+    // Wall-clock start for per-call usage telemetry (#576). Captured here so the
+    // emitted duration covers the full request/response/parse cycle of a single
+    // attempt, not the retry-wrapping `chatCompletion`.
+    const requestStartedAt = Date.now();
     let response;
     try {
         response = await fetchWithTimeout(config.endpoint, {
@@ -241,6 +265,16 @@ async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     catch {
         throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactErrorBody(rawOkBody)}`, "parse_error", response.status);
     }
+    // Per-call usage telemetry (#576). Best-effort and fully isolated: a missing
+    // or garbled usage block still records duration + model, and a throwing sink
+    // can never fail the call (emitLlmUsage swallows its own errors). The stage
+    // is supplied ambiently by emitLlmUsage; no `stage` param is threaded here.
+    emitLlmUsage({
+        model: typeof json.model === "string" && json.model ? json.model : config.model,
+        durationMs: Date.now() - requestStartedAt,
+        finishReason: typeof json.choices?.[0]?.finish_reason === "string" ? json.choices[0].finish_reason : undefined,
+        ...extractUsageTokens(json.usage),
+    });
     const content = (json.choices?.[0]?.message?.content ?? "").trim();
     const reasoning = (json.choices?.[0]?.message?.reasoning_content ?? "").trim();
     return content || reasoning;

package/dist/llm/embedder.js

@@ -2,7 +2,7 @@
 // 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 { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache.js";
-import { isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
+import { DEFAULT_LOCAL_MODEL, isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
 export { clearEmbeddingCache } from "./embedders/cache.js";
@@ -52,7 +52,8 @@ export async function embed(text, embeddingConfig, signal) {
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
- * Falls back to sequential embedding for the local transformer pipeline.
+ * Uses the LocalEmbedder.embedBatch path for the local transformer pipeline,
+ * which processes texts in chunks of 32 for genuine batched inference.
  */
 export async function embedBatch(texts, embeddingConfig, signal) {
     if (texts.length === 0)
@@ -60,8 +61,13 @@ export async function embedBatch(texts, embeddingConfig, signal) {
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         return new RemoteEmbedder(embeddingConfig).embedBatch(texts, signal);
     }
-    // Local transformer: process sequentially (pipeline handles one at a time)
+    // Local transformer: use the batched path (chunks of 32 via LocalEmbedder).
+    // When a localModel override is set we cannot share the singleton (which uses
+    // the default model), so fall back to per-text embedWithModel in that case.
     const localModel = embeddingConfig?.localModel;
+    if (!localModel) {
+        return getLocalEmbedder().embedBatch(texts, signal);
+    }
     const results = [];
     for (const text of texts) {
         if (signal?.aborted) {
@@ -77,6 +83,24 @@ export async function embedBatch(texts, embeddingConfig, signal) {
 // facade and its `@huggingface/transformers` import chain. Re-export
 // preserves the existing public API.
 export { cosineSimilarity } from "./embedders/types.js";
+// ── Model ID resolution ─────────────────────────────────────────────────────
+/**
+ * Derive a stable string identifier for the embedding model in use.
+ * This is the `model_id` stored in `body_embeddings` (and used for the
+ * drop-all-on-mismatch purge when the model changes).
+ *
+ * Rules:
+ *   - Remote endpoint: use `config.model` (the API-level model name).
+ *   - Local transformers: use `config.localModel ?? DEFAULT_LOCAL_MODEL`.
+ *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
+ */
+export function resolveEmbeddingModelId(embeddingConfig) {
+    if (!embeddingConfig)
+        return DEFAULT_LOCAL_MODEL;
+    if (hasRemoteEndpoint(embeddingConfig))
+        return embeddingConfig.model ?? "remote";
+    return embeddingConfig.localModel ?? DEFAULT_LOCAL_MODEL;
+}
 // ── Availability check ──────────────────────────────────────────────────────
 /**
  * Check whether embedding is available with a detailed reason on failure.

package/dist/llm/embedders/local.js

@@ -19,8 +19,24 @@ import { getDirname, resolveModule } from "../../runtime.js";
  * `all-MiniLM-L6-v2` at the same 384-dimension footprint.
  */
 export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
+/** Type-guard: true when the value looks like a batch Tensor (has .dims). */
+function isBatchTensor(v) {
+    return (v !== null &&
+        typeof v === "object" &&
+        "data" in v &&
+        "dims" in v &&
+        Array.isArray(v.dims) &&
+        v.dims.length >= 2);
+}
 const LOCAL_EMBEDDER_DTYPE = "fp32";
 const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
+/**
+ * Maximum texts per batch for the local transformers pipeline. The pipeline
+ * can run genuine batched inference over a string array; 32 is a safe default
+ * that fits well inside most model context budgets while providing 10–50×
+ * throughput improvement over one-at-a-time calls on the cold minority.
+ */
+const LOCAL_BATCH_SIZE = 32;
 /**
  * Return the local model name that will be used for embedding.
  * When `overrideModel` is provided it takes precedence; otherwise
@@ -77,15 +93,63 @@ export class LocalEmbedder {
         }
         return this.embedWithModel(text, this.defaultModel);
     }
+    /**
+     * Embed a batch of texts. Processes in chunks of `LOCAL_BATCH_SIZE` (32) so
+     * the transformers pipeline can run genuine batched inference rather than one
+     * call per text. Falls back to one-at-a-time if the pipeline does not support
+     * array input (older versions of @huggingface/transformers). Each chunk is
+     * checked against the AbortSignal between calls.
+     */
     async embedBatch(texts, signal) {
         if (texts.length === 0)
             return [];
+        if (signal?.aborted) {
+            throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
+        }
+        const pipeline = await this.getPipeline(this.defaultModel);
         const results = [];
-        for (const text of texts) {
+        for (let i = 0; i < texts.length; i += LOCAL_BATCH_SIZE) {
             if (signal?.aborted) {
                 throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
             }
-            results.push(await this.embedWithModel(text, this.defaultModel));
+            const chunk = texts.slice(i, i + LOCAL_BATCH_SIZE);
+            try {
+                // @huggingface/transformers feature-extraction pipeline accepts a
+                // string[] and returns a batch Tensor (NOT an Array<{data}>).
+                // The Tensor has .data (flat Float32Array, length = batch * dim) and
+                // .dims = [batch, dim]. Slice .data into per-row vectors using .dims.
+                const batchResult = await pipeline(chunk, {
+                    pooling: "mean",
+                    normalize: true,
+                });
+                if (isBatchTensor(batchResult)) {
+                    const dim = batchResult.dims[1];
+                    for (let row = 0; row < chunk.length; row++) {
+                        results.push(Array.from(batchResult.data.subarray(row * dim, (row + 1) * dim)));
+                    }
+                }
+                else if (Array.isArray(batchResult)) {
+                    // Older versions of @huggingface/transformers returned Array<{data}>.
+                    for (const r of batchResult) {
+                        results.push(Array.from(r.data));
+                    }
+                }
+                else {
+                    // Single-text result returned for a chunk — should not happen for
+                    // string[] input, but handle defensively.
+                    throw new Error("unexpected pipeline return shape for batch input");
+                }
+            }
+            catch {
+                // Fallback: process one-at-a-time (older pipeline versions or mismatched
+                // return type). Fail-open per text: a single failure aborts the chunk.
+                for (const text of chunk) {
+                    if (signal?.aborted) {
+                        throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
+                    }
+                    results.push(await this.embedWithModel(text, this.defaultModel));
+                }
+            }
         }
         return results;
     }

package/dist/llm/graph-extract.js

@@ -20,6 +20,7 @@
  * the connection via `resolveIndexPassLLM("graph", config)` and pass it
  * straight through.
  */
+import systemPromptTemplate from "../assets/prompts/graph-extract-system.md" with { type: "text" };
 import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn, warnVerbose } from "../core/warn.js";
@@ -41,7 +42,7 @@ const NON_ARRAY_BATCH_DISABLE_THRESHOLD = 2;
 const MAX_ENTITIES_PER_ASSET = 32;
 /** Hard cap on relations returned per asset. */
 const MAX_RELATIONS_PER_ASSET = 32;
-const SYSTEM_PROMPT = "You extract a knowledge graph from developer notes. Return ONLY valid JSON — no prose, no markdown fences, no preamble.";
+const SYSTEM_PROMPT = systemPromptTemplate;
 const USER_PROMPT_PREFIX = userPromptTemplate
     .replace("{{MAX_ENTITIES}}", String(MAX_ENTITIES_PER_ASSET))
     .replace("{{MAX_RELATIONS}}", String(MAX_RELATIONS_PER_ASSET));

package/dist/llm/memory-infer.js

@@ -18,20 +18,16 @@
  * the connection via `resolveIndexPassLLM("memory", config)` and pass it
  * straight through.
  */
+import memoryInferSystemPrompt from "../assets/prompts/memory-infer-system.md" with { type: "text" };
+import memoryInferUserPrompt from "../assets/prompts/memory-infer-user.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn } from "../core/warn.js";
 import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
 /** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
 const MAX_BODY_CHARS = 4000;
-const SYSTEM_PROMPT = "You compress a developer memory into one high-signal derived memory for later retrieval. " +
-    "Return only valid JSON. No prose outside the JSON object. No markdown fences.";
-const USER_PROMPT_PREFIX = `Compress the memory below into one derived memory. Output ONLY JSON:
-{"title":"short title string","description":"one sentence summary string","tags":["tag1","tag2"],"searchHints":["search phrase 1","search phrase 2"],"content":"2-3 sentence compressed body preserving key facts verbatim"}
-Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, 3-8 tags, 3-6 searchHints. The content field must be a plain string with 2-3 sentences.
-
-Memory:
-`;
+const SYSTEM_PROMPT = memoryInferSystemPrompt;
+const USER_PROMPT_PREFIX = memoryInferUserPrompt;
 /**
  * Strict JSON Schema for the derived-memory payload. Sent to providers that
  * opt in via `LlmConnectionConfig.supportsJsonSchema = true`; the client

package/dist/llm/metadata-enhance.js

@@ -1,9 +1,17 @@
 // 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/.
+/**
+ * LLM-driven metadata enhancement for stash entries.
+ *
+ * Split out of `llm.ts` so the higher-level workflow (prompting the LLM to
+ * improve descriptions/tags/searchHints) lives separately from the low-level
+ * transport client in `client.ts`.
+ */
+import metadataEnhanceSystemPrompt from "../assets/prompts/metadata-enhance-system.md" with { type: "text" };
 import { chatCompletion, parseJsonResponse } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
-const SYSTEM_PROMPT = `You are a metadata generator for a developer asset registry. Given a script/skill/command/agent entry, generate improved metadata. Respond with ONLY valid JSON, no markdown fencing.`;
+const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,
  * generate searchHints, and suggest tags.

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);
+}