akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

package/dist/llm/graph-extract.js

@@ -7,7 +7,7 @@
  * Given a single asset body (typically a `memory:` or `knowledge:` file),
  * asks the configured LLM to surface the entities mentioned in it and the
  * relations between them. The pass itself
- * (`src/indexer/graph-extraction.ts`) is responsible for deciding which
+ * (`src/indexer/graph/graph-extraction.ts`) is responsible for deciding which
  * files to extract, persisting the resulting nodes/edges to the index DB,
  * and feeding the graph data into the FTS5+boosts
  * search pipeline as a single boost component.
@@ -15,16 +15,15 @@
  * This module is intentionally tiny and stateless so tests can stub it via
  * `mock.module("../src/llm/graph-extract", ...)` without hitting a network.
  *
- * Locked v1 contract (#208): the LLM connection always comes from the
- * selected named LLM engine. Callers obtain
- * the connection via `resolveIndexPassLLM("graph", config)` and pass it
- * straight through.
+ * The LLM connection comes from the selected named engine. Callers obtain it
+ * 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 { parseEmbeddedJsonResponse } from "../core/parse.js";
 import { warn, warnVerbose } from "../core/warn.js";
-import { chatCompletion, isContextSizeError, parseEmbeddedJsonResponse } from "./client.js";
+import { chatCompletion, isContextSizeError } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
 import { callStructured } from "./structured-call.js";
 /**
@@ -47,11 +46,6 @@ 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));
-// `isContextSizeError` is defined in `./client` and re-exported here so the
-// graph extractor and the retry classifier (`isRetryable`) share one
-// definition (#496). Re-exported (not just imported) to preserve existing
-// importers of this module — including its unit test.
-export { isContextSizeError } from "./client.js";
 const GENERIC_ENTITIES = new Set([
     "agent",
     "application",

package/dist/llm/memory-infer.js

@@ -1,4 +1,147 @@
 // 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/.
-export { compressMemoryToDerivedMemory, } from "./memory-infer-impl.js";
+/**
+ * LLM helper for the `akm index` memory-inference pass (#201).
+ *
+ * Compresses a single memory body into one higher-signal derived memory. The
+ * pass itself (in `src/indexer/passes/memory-inference.ts`) is responsible for
+ * deciding which memories are pending, persisting the derived memory with the
+ * correct frontmatter (`inferred: true`, `source: <parent-ref>`), and marking
+ * the parent as processed for idempotency.
+ *
+ * This module is intentionally tiny and stateless so tests can stub it via
+ * `mock.module("../src/llm/memory-infer", ...)` without hitting a network.
+ *
+ * The LLM connection comes from the selected named engine. Callers obtain it
+ * 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 { parseEmbeddedJsonResponse } from "../core/parse.js";
+import { warn } from "../core/warn.js";
+import { callStructured } from "./structured-call.js";
+/** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
+const MAX_BODY_CHARS = 4000;
+const SYSTEM_PROMPT = memoryInferSystemPrompt;
+const USER_PROMPT_PREFIX = memoryInferUserPrompt;
+const PROMPT_PLACEHOLDERS = new Set([
+    "short title string",
+    "one sentence summary string",
+    "tag1",
+    "tag2",
+    "search phrase 1",
+    "search phrase 2",
+    "2-3 sentence compressed body preserving key facts verbatim",
+]);
+/**
+ * Strict JSON Schema for the derived-memory payload. Sent to providers that
+ * opt in via `ChatCompletionConfig.supportsJsonSchema = true`; the client
+ * silently drops the schema for providers that don't.
+ *
+ * Extends the responseSchema lift (PR 1, asset-writers-investigation §5) to
+ * the memory-inference path. Mirrors the validation gate below
+ * (title/description/content + non-empty tags/searchHints) so a
+ * schema-compliant response is guaranteed to pass the downstream check
+ * — no more "incomplete derived memory payload from LLM; skipping memory"
+ * for shape-only failures.
+ */
+const DERIVED_MEMORY_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        title: { type: "string", minLength: 1 },
+        description: { type: "string", minLength: 1 },
+        content: { type: "string", minLength: 1 },
+        tags: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 8 },
+        searchHints: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 6 },
+    },
+    required: ["title", "description", "content", "tags", "searchHints"],
+    additionalProperties: false,
+};
+/**
+ * Compress a single memory body into one derived memory via the configured LLM.
+ *
+ * Returns `undefined` on any failure (timeout, invalid JSON, empty response).
+ * Errors are logged via `warn()` but never thrown — a failed split for one memory
+ * must not abort the rest of the index pass.
+ *
+ * Routes through `callStructured({ feature: "memory_inference", ... })` so the
+ * feature gate, error classification, and onFallback hook are honoured uniformly
+ * (Fix C5).
+ */
+export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt) {
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return undefined;
+    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
+    // Memory inference is always gated: no config closes the gate instead of
+    // taking callStructured's ungated path for direct callers.
+    if (!akmConfig) {
+        onFallback?.({ feature: "memory_inference", reason: "disabled" });
+        return undefined;
+    }
+    return callStructured({
+        feature: "memory_inference",
+        akmConfig,
+        config: llmConfig,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ],
+        request: {
+            temperature: 0.1,
+            timeoutMs: llmConfig.timeoutMs,
+            signal,
+            responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
+            onRetryAttempt,
+        },
+        parse: (raw) => {
+            if (!raw)
+                return undefined;
+            const parsed = parseEmbeddedJsonResponse(raw);
+            if (!parsed) {
+                warn("memory inference: invalid JSON response from LLM; skipping memory.");
+                return undefined;
+            }
+            const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
+            const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
+            const content = typeof parsed.content === "string" ? parsed.content.trim() : "";
+            const tags = Array.isArray(parsed.tags)
+                ? parsed.tags
+                    .filter((t) => typeof t === "string")
+                    .map((t) => t.trim())
+                    .filter(Boolean)
+                    .slice(0, 8)
+                : [];
+            const searchHints = Array.isArray(parsed.searchHints)
+                ? parsed.searchHints
+                    .filter((h) => typeof h === "string")
+                    .map((h) => h.trim())
+                    .filter(Boolean)
+                    .slice(0, 6)
+                : [];
+            if (!title || !description || !content || tags.length === 0 || searchHints.length === 0) {
+                warn("memory inference: incomplete derived memory payload from LLM; skipping memory.");
+                return undefined;
+            }
+            if ([title, description, content, ...tags, ...searchHints].some((value) => PROMPT_PLACEHOLDERS.has(value.toLowerCase()))) {
+                warn("memory inference: prompt placeholder response from LLM; skipping memory.");
+                return undefined;
+            }
+            return { title, description, tags, searchHints, content };
+        },
+        onError: (cls, err) => {
+            if (cls === "html") {
+                if (telemetry)
+                    telemetry.htmlErrorCount = (telemetry.htmlErrorCount ?? 0) + 1;
+                warn(`memory inference: provider returned HTML instead of JSON; skipping memory: ${toErrorMessage(err)}`);
+                return undefined;
+            }
+            warn(`memory inference failed: ${toErrorMessage(err)}`);
+            return undefined;
+        },
+        fallback: undefined,
+        onFallback,
+    });
+}

package/dist/llm/metadata-enhance.js

@@ -4,12 +4,11 @@
 /**
  * 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`.
+ * Keeps the higher-level workflow for improving descriptions, tags, and search
+ * hints separate from the low-level transport client.
  */
 import metadataEnhanceSystemPrompt from "../assets/prompts/metadata-enhance-system.md" with { type: "text" };
-import { parseJsonResponse } from "./client.js";
+import { parseJsonResponse } from "../core/parse.js";
 import { callStructured } from "./structured-call.js";
 const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
 /**
@@ -20,9 +19,8 @@ const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
  * `tryLlmFeature("metadata_enhance", ...)` so the feature gate is honoured: a
  * closed gate yields `{ status: "skipped" }` and a thrown/timed-out call yields
  * `{ status: "failed" }` — neither is reported as an enrichment. When
- * `akmConfig` is `undefined` the gate is bypassed entirely — the LLM call runs
- * unconditionally and errors propagate to the caller (pre-gate behaviour, used
- * by direct callers such as tests).
+ * `akmConfig` is `undefined` the gate is bypassed entirely: the LLM call runs
+ * unconditionally and errors propagate to direct callers such as tests.
  */
 export async function enhanceMetadata(config, entry, fileContent, signal, akmConfig) {
     const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];

package/dist/llm/structured-call.js

@@ -1,7 +1,7 @@
 // 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 { chatCompletion, isContextSizeError, LlmCallError } from "./client.js";
+import { chatCompletion, isContextSizeError, LlmCallError, } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
 /**
  * Classify a thrown LLM error into one of the three buckets. This is the single

package/dist/llm/usage-persist.js

@@ -23,12 +23,18 @@ 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";
+/** Event type for the owning sink's terminal-record count marker. */
+export const LLM_USAGE_SUMMARY_EVENT = "llm_usage_summary";
 /**
  * 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 };
+    const metadata = {
+        durationMs: record.durationMs,
+        outcome: record.outcome,
+        modelSource: record.modelSource,
+    };
     if (record.stage !== undefined)
         metadata.stage = record.stage;
     if (record.engine !== undefined)
@@ -47,6 +53,8 @@ function toEventMetadata(record) {
         metadata.totalTokens = record.totalTokens;
     if (record.reasoningTokens !== undefined)
         metadata.reasoningTokens = record.reasoningTokens;
+    if (record.errorCode !== undefined)
+        metadata.errorCode = record.errorCode;
     return metadata;
 }
 /**
@@ -56,20 +64,33 @@ function toEventMetadata(record) {
  * 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.
+ * opened for its other events. A getter is resolved for every append so a
+ * caller can replace its context binding without replacing this owning sink.
+ * When omitted, `appendEvent` falls back to its default open-insert-close path.
  */
 export function installLlmUsagePersistence(ctx) {
+    let expectedTerminalRecords = 0;
+    let disposed = false;
     setLlmUsageSink((record) => {
-        appendEvent({ eventType: LLM_USAGE_EVENT, metadata: toEventMetadata(record) }, ctx);
+        expectedTerminalRecords += 1;
+        appendEvent({ eventType: LLM_USAGE_EVENT, metadata: toEventMetadata(record) }, typeof ctx === "function" ? ctx() : ctx);
     });
     return () => {
+        if (disposed)
+            return;
+        disposed = true;
         clearLlmUsageSink();
+        try {
+            appendEvent({ eventType: LLM_USAGE_SUMMARY_EVENT, metadata: { expectedTerminalRecords } }, typeof ctx === "function" ? ctx() : ctx);
+        }
+        catch {
+            // Persistence remains best-effort even during run teardown.
+        }
     };
 }
 /**
  * Like {@link installLlmUsagePersistence}, but a no-op when a sink is already
- * installed — used by standalone entry points (`akm consolidate`, `akm drain`)
+ * 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.

package/dist/llm/usage-telemetry.js

@@ -5,7 +5,8 @@
  * 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
+ * EVERY OpenAI-compatible HTTP attempt and emits one terminal
+ * {@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
@@ -87,6 +88,20 @@ function asFiniteNonNegative(value) {
 function asNonEmptyString(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+function asLlmUsageErrorCode(value) {
+    switch (value) {
+        case "rate_limited":
+        case "provider_error":
+        case "provider_html_error":
+        case "network_error":
+        case "parse_error":
+        case "timeout":
+        case "unknown_error":
+            return value;
+        default:
+            return undefined;
+    }
+}
 /** Decode durable event metadata with the same validation used by health aggregation. */
 export function decodeLlmUsageRecord(value) {
     if (!value || typeof value !== "object")
@@ -95,7 +110,12 @@ export function decodeLlmUsageRecord(value) {
     const durationMs = asFiniteNonNegative(raw.durationMs);
     if (durationMs === undefined)
         return undefined;
-    const record = { durationMs };
+    // Historical rows predate terminal provenance. Keep health aggregation
+    // backward-compatible while conservatively treating their model as configured,
+    // never response-observed.
+    const outcome = raw.outcome === "success" || raw.outcome === "error" ? raw.outcome : "success";
+    const modelSource = raw.modelSource === "response" || raw.modelSource === "configured" ? raw.modelSource : "configured";
+    const record = { durationMs, outcome, modelSource };
     for (const key of ["stage", "engine", "process", "model", "finishReason"]) {
         const decoded = asNonEmptyString(raw[key]);
         if (decoded !== undefined)
@@ -106,6 +126,9 @@ export function decodeLlmUsageRecord(value) {
         if (decoded !== undefined)
             record[key] = decoded;
     }
+    const errorCode = asLlmUsageErrorCode(raw.errorCode);
+    if (errorCode !== undefined)
+        record.errorCode = errorCode;
     return record;
 }
 /**

package/dist/output/cli-hints.js

@@ -2,8 +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/.
 /**
- * Embedded "agent CLI hints" rendered by `akm hints` when no other source
- * is available.
+ * Embedded agent CLI guide rendered by `akm hints` and `akm help agents`.
  *
  * Extracted from `src/cli.ts` so it does not bloat the CLI module and so
  * docs/CI tooling can re-use the same constants. Two flavors:

package/dist/output/context.js

@@ -9,7 +9,9 @@
  * calls read from this in-memory singleton instead of re-scanning argv and
  * re-loading config on every call.
  *
- * Initialized from `cli.ts` before `runMain`.
+ * Initialized from `cli.ts` before `runCli` dispatches the command (`cli.ts`
+ * drives citty's `runCommand` directly rather than `runMain` — see the
+ * top-level driver comment there).
  */
 import { UsageError } from "../core/errors.js";
 const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md", "html"];
@@ -39,6 +41,8 @@ function parseShapeMode(value) {
 export function parseFlagValue(argv, flag) {
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
+        if (arg === "--")
+            break;
         if (arg === flag)
             return argv[i + 1];
         if (arg.startsWith(`${flag}=`))
@@ -47,15 +51,26 @@ export function parseFlagValue(argv, flag) {
     return undefined;
 }
 export function hasBooleanFlag(argv, flag) {
-    return argv.some((arg) => arg === flag || arg === `${flag}=true`);
+    for (const arg of argv) {
+        if (arg === "--")
+            return false;
+        if (arg === flag || arg === `${flag}=true`)
+            return true;
+    }
+    return false;
 }
 /**
  * Read a hyphenated arg out of citty's parsed `args` object.
  *
- * citty does not auto-camelise hyphenated arg keys (see `--max-pages`,
- * `--with-sources` for the existing convention), so command handlers end up
- * casting `args` to a string-indexed record at every read site. This helper
- * encapsulates the cast.
+ * Verified live: citty DOES auto-camelise a DECLARED hyphenated arg — for
+ * `"max-pages": { type: "string" }` in a command's `args`, citty's parsed
+ * object answers both `args["max-pages"]` and `args.maxPages` (a `Proxy`
+ * falls back through `camelCase`/`kebabCase`, and `--no-<flag>` negation is
+ * handled the same way for booleans). What citty's own TS types do NOT give
+ * callers is a statically-typed handle on that mapping, and command handlers
+ * here type `args` as `unknown` at the boundary — so every read site still
+ * needs a cast. This helper encapsulates that cast; it exists for typing
+ * convenience, not to work around a citty parsing limitation.
  */
 export function getHyphenatedArg(args, key) {
     if (typeof args !== "object" || args === null)
@@ -81,7 +96,7 @@ export function resolveOutputMode(argv, defaults = {}) {
     const detail = parseDetailLevel(rawDetail) ?? defaults?.detail ?? "brief";
     const shape = parseShapeMode(rawShape) ?? "human";
     const outputPath = parseFlagValue(argv, "--output");
-    return { format, detail, shape, forAgent: shape === "agent", ...(outputPath ? { outputPath } : {}) };
+    return { format, detail, shape, ...(outputPath ? { outputPath } : {}) };
 }
 let _mode;
 /**

package/dist/output/format-exempt.js

@@ -0,0 +1,80 @@
+// 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/.
+/**
+ * Commands whose output is not an envelope, and therefore not formattable (D7).
+ *
+ * D7 makes all six `--format` values work on every command that renders through
+ * `output()`. A small set does not render an envelope at all: they emit a shell
+ * script, drive an interactive prompt, hand stdout to a child process, or print
+ * a document that IS the payload. Passing `--format` to one of those cannot do
+ * anything useful.
+ *
+ * The point of declaring the set here is that the exemption stops being
+ * implicit. Before D7 you discovered it by getting JSON when you asked for
+ * Markdown, or an exit 2 when you asked for HTML. Now the list is one grep away,
+ * it is documented in `STABILITY.md`, and asking for a format on an exempt
+ * command warns instead of silently doing something else.
+ *
+ * Names are canonical command paths resolved from the Citty tree.
+ */
+/**
+ * Top-level command tokens whose entire surface is format-exempt.
+ */
+const EXEMPT_COMMANDS = new Set([
+    // Emits shell completion script source for eval.
+    "completions",
+    // `migrate status`/`apply` used to be exempt here too: `runMigrationTool`
+    // (src/commands/migration-tool.ts) spawns the standalone
+    // `scripts/akm-migrate.ts` tool, which always emitted its own fixed JSON
+    // shape and never consulted `--format`. `src/commands/migrate-cli.ts` now
+    // parses that child's final result line and renders it through the normal
+    // `output()` pipeline (registered shape: `src/output/shapes/migrate.ts`;
+    // text renderer: `src/output/text/migrate.ts`), so both subcommands honour
+    // `--format` like any other command and are no longer listed here. Any
+    // progress-event lines the child prints during a real `apply` still print
+    // verbatim ahead of the formatted result — those are operational logging,
+    // not part of the result envelope, the same way a progress spinner would be.
+    // Document payload group: bare `help` prints the sectioned overview,
+    // `help migrate <version>` prints release notes, and `help agents` prints
+    // the embedded CLI-reference guide (`src/output/cli-hints.ts`) — none of
+    // the three render a result envelope.
+    "help",
+    // Embedded agent guide document.
+    "hints",
+]);
+/**
+ * `<command> <subcommand>` pairs that are exempt while the rest of the group
+ * formats normally.
+ */
+const EXEMPT_SUBCOMMANDS = new Set([
+    // Child-process passthrough (the env/secret groups otherwise format fine).
+    "env run",
+    "secret run",
+    // B3/B4 (W1-F): a bare absolute filesystem path IS the payload — the
+    // documented shell-substitution primitive (`$(akm env path <ref>)`,
+    // Docker `_FILE` / `--env-file`) — not a field worth wrapping in an
+    // envelope. Wrapping it broke every existing substitution silently: the
+    // CLI's default format is `json`, so an un-flagged `akm env path <ref>`
+    // (exactly how the substitution is always written) started emitting
+    // `{"path":"..."}` instead of the raw path. Unlike `config path`, this
+    // command has no `--all`-style multi-field variant, so the whole surface
+    // can be exempt without wrongly warning on a real envelope case.
+    "env path",
+]);
+/**
+ * True when `--format` cannot meaningfully apply to this invocation.
+ *
+ * `commandPath` contains canonical Citty command names from the top-level
+ * command through the deepest resolved subcommand.
+ */
+export function isFormatExemptCommand(commandPath) {
+    const command = commandPath[0];
+    if (command === undefined)
+        return false;
+    return EXEMPT_COMMANDS.has(command) || EXEMPT_SUBCOMMANDS.has(commandPath.join(" "));
+}
+/** The declared exempt set, for docs generation and tests. */
+export function formatExemptSurfaces() {
+    return { commands: [...EXEMPT_COMMANDS], subcommands: [...EXEMPT_SUBCOMMANDS] };
+}