akm-cli 0.6.1 → 0.7.0

package/dist/{commands → src/commands}/config-cli.js

@@ -31,6 +31,12 @@ export function parseConfigValue(key, value) {
             return { embedding: mergeLlmLikeEmbedding(undefined, { model: requireNonEmptyString(value, key) }) };
         case "embedding.apiKey":
             return { embedding: mergeLlmLikeEmbedding(undefined, { apiKey: requireNonEmptyString(value, key) }) };
+        case "embedding.contextLength":
+            return { embedding: mergeLlmLikeEmbedding(undefined, { contextLength: parsePositiveInteger(value, key) }) };
+        case "embedding.ollamaOptions.numCtx":
+            return {
+                embedding: mergeLlmLikeEmbedding(undefined, { ollamaOptions: { num_ctx: parsePositiveInteger(value, key) } }),
+            };
         case "llm":
             return { llm: parseLlmConnectionValue(value) };
         case "llm.endpoint":
@@ -62,9 +68,10 @@ export function parseConfigValue(key, value) {
         case "security.installAudit.allowedFindings":
             return { security: { installAudit: { allowedFindings: parseAllowedFindingsValue(value, key) } } };
         default:
-            throw new UsageError(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`, "INVALID_FLAG_VALUE", UNKNOWN_CONFIG_KEY_HINT);
     }
 }
+const UNKNOWN_CONFIG_KEY_HINT = "Valid top-level keys: stashDir, embedding, llm, registries, sources, agent, output, semanticSearchMode. Use dotted paths like `embedding.endpoint` or `output.format` for nested values.";
 export function getConfigValue(config, key) {
     switch (key) {
         case "stashDir":
@@ -81,6 +88,10 @@ export function getConfigValue(config, key) {
             return config.embedding?.model ?? null;
         case "embedding.apiKey":
             return config.embedding?.apiKey ?? null;
+        case "embedding.contextLength":
+            return config.embedding?.contextLength ?? null;
+        case "embedding.ollamaOptions.numCtx":
+            return config.embedding?.ollamaOptions?.num_ctx ?? null;
         case "llm":
             return config.llm ?? null;
         case "llm.endpoint":
@@ -114,7 +125,7 @@ export function getConfigValue(config, key) {
         case "security.installAudit.allowedFindings":
             return config.security?.installAudit?.allowedFindings ?? null;
         default:
-            throw new UsageError(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`, "INVALID_FLAG_VALUE", UNKNOWN_CONFIG_KEY_HINT);
     }
 }
 export function setConfigValue(config, key, rawValue) {
@@ -151,6 +162,18 @@ export function setConfigValue(config, key, rawValue) {
                 ...config,
                 embedding: mergeLlmLikeEmbedding(config.embedding, { apiKey: requireNonEmptyString(rawValue, key) }),
             };
+        case "embedding.contextLength":
+            return {
+                ...config,
+                embedding: mergeLlmLikeEmbedding(config.embedding, { contextLength: parsePositiveInteger(rawValue, key) }),
+            };
+        case "embedding.ollamaOptions.numCtx":
+            return {
+                ...config,
+                embedding: mergeLlmLikeEmbedding(config.embedding, {
+                    ollamaOptions: { ...(config.embedding?.ollamaOptions ?? {}), num_ctx: parsePositiveInteger(rawValue, key) },
+                }),
+            };
         case "llm.endpoint":
             return { ...config, llm: mergeLlmLike(config.llm, { endpoint: requireNonEmptyString(rawValue, key) }) };
         case "llm.model":
@@ -168,7 +191,7 @@ export function setConfigValue(config, key, rawValue) {
             return { ...config, defaultWriteTarget: name };
         }
         default:
-            throw new UsageError(`Unknown config key: ${key}`);
+            throw new UsageError(`Unknown config key: ${key}`, "INVALID_FLAG_VALUE", UNKNOWN_CONFIG_KEY_HINT);
     }
 }
 export function unsetConfigValue(config, key) {
@@ -189,6 +212,19 @@ export function unsetConfigValue(config, key) {
             const { apiKey: _a, ...rest } = config.embedding;
             return { ...config, embedding: rest };
         }
+        case "embedding.contextLength": {
+            if (!config.embedding)
+                return config;
+            const { contextLength: _cl, ...rest } = config.embedding;
+            return { ...config, embedding: rest };
+        }
+        case "embedding.ollamaOptions.numCtx": {
+            if (!config.embedding?.ollamaOptions)
+                return config;
+            const { num_ctx: _nc, ...restOpts } = config.embedding.ollamaOptions;
+            const ollamaOptions = Object.keys(restOpts).length > 0 ? restOpts : undefined;
+            return { ...config, embedding: { ...config.embedding, ollamaOptions } };
+        }
         case "llm":
             return { ...config, llm: undefined };
         case "llm.endpoint":
@@ -241,7 +277,7 @@ export function unsetConfigValue(config, key) {
                 }),
             };
         default:
-            throw new UsageError(`Unknown or unsupported unset key: ${key}`);
+            throw new UsageError(`Unknown or unsupported unset key: ${key}`, "INVALID_FLAG_VALUE", UNKNOWN_CONFIG_KEY_HINT);
     }
 }
 export function listConfig(config) {
@@ -478,6 +514,13 @@ function parseUnknownPositiveInteger(value, key) {
     }
     return value;
 }
+function parsePositiveInteger(value, key) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || !Number.isInteger(n) || n <= 0) {
+        throw new UsageError(`Invalid value for ${key}: expected a positive integer`);
+    }
+    return n;
+}
 function parseStashesValue(value) {
     if (value === "null" || value === "")
         return undefined;

package/dist/src/commands/distill.js

@@ -0,0 +1,283 @@
+/**
+ * `akm distill <ref>` — feedback distillation into lesson proposals (#228).
+ *
+ * The command reads a target asset and any recent feedback events about it,
+ * asks an LLM to distil a *lesson* (per v1 spec §13) the agent should
+ * remember next time, and queues the result as a {@link Proposal} (source
+ * `"distill"`). The proposal queue is the *only* path to a live asset — this
+ * command never mutates source files directly. Acceptance is a human (or
+ * automated) decision via `akm proposal accept`.
+ *
+ * # Architectural seams
+ *
+ *   - **Single bounded in-tree LLM call.** Wrapped in {@link tryLlmFeature}
+ *     under the `feedback_distillation` gate (v1 spec §14). The wrapper
+ *     enforces the 30 s hard timeout and converts disable / throw / timeout
+ *     into a `null` return from `fn`, which we treat as a graceful
+ *     "skipped" outcome (exit 0, no proposal, `distill_invoked` event with
+ *     `outcome: "skipped"`).
+ *   - **Stateless.** No module-level state — every callable is a pure
+ *     function of its arguments and an injectable `chat` seam. The
+ *     architecture seam test (`tests/architecture/llm-stateless-seam.test.ts`)
+ *     applies.
+ *   - **Output substrate.** Proposal creation goes through the `proposals`
+ *     module so distill shares its persistence + validation pipeline with
+ *     `akm reflect` / `akm propose`. Validation failures (LLM returned a
+ *     lesson without required `description` / `when_to_use` frontmatter) are
+ *     a *different* graceful path: no proposal is created, the structured
+ *     error is surfaced, and the command exits non-zero.
+ *
+ * # Lesson-name derivation rule
+ *
+ * The proposed lesson ref is `lesson:<original-ref-slug>-lesson`, where
+ * `<original-ref-slug>` is `<type>-<name>` from the parsed input ref (so
+ * `skill:deploy` → `lesson:skill-deploy-lesson`, and `team//memory:auth-tips`
+ * → `lesson:memory-auth-tips-lesson`). Origin prefixes are dropped from the
+ * derived name so two sources with the same asset-type/name collapse onto
+ * the same lesson queue entry rather than each generating its own — the
+ * proposal queue tolerates duplicate refs (id is a UUID), so the human
+ * reviewer can decide which one to accept.
+ *
+ * # Why we do not call `runAgent`
+ *
+ * Distillation is in-tree per the v1 spec ("bounded in-tree LLM call"). The
+ * agent dispatch path is a heavier shell-out used by the curator/agent
+ * surfaces — distill must be cheap, deterministic-ish, and bounded so it can
+ * be invoked from CI / automation without spinning up an agent harness.
+ */
+import fs from "node:fs";
+import { parseAssetRef } from "../core/asset-ref";
+import { resolveStashDir } from "../core/common";
+import { loadConfig } from "../core/config";
+import { ConfigError, UsageError } from "../core/errors";
+import { appendEvent, readEvents } from "../core/events";
+import { parseFrontmatter } from "../core/frontmatter";
+import { lintLessonContent } from "../core/lesson-lint";
+import { createProposal } from "../core/proposals";
+import { lookup as indexerLookup } from "../indexer/indexer";
+import { chatCompletion } from "../llm/client";
+import { tryLlmFeature } from "../llm/feature-gate";
+// ── Lesson-ref derivation ───────────────────────────────────────────────────
+/** Derive the proposed lesson ref from the input ref. See module docblock. */
+export function deriveLessonRef(inputRef) {
+    const parsed = parseAssetRef(inputRef);
+    // Strip origin: a feedback signal recorded against `team//skill:deploy`
+    // distils into the same lesson namespace as `skill:deploy`. The proposal
+    // id (a UUID) keeps the queue entries distinct, so collisions are not a
+    // problem — and reviewers want to see them next to each other anyway.
+    const slug = `${parsed.type}-${parsed.name}`.toLowerCase();
+    // Replace anything outside the canonical asset-name charset with `-`. Keep
+    // it deterministic so re-runs produce the same ref.
+    const safe = slug
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/-+/g, "-")
+        .replace(/^-|-$/g, "");
+    return `lesson:${safe}-lesson`;
+}
+// ── Prompt assembly ─────────────────────────────────────────────────────────
+const SYSTEM_PROMPT = [
+    "You are the akm `distill` distiller.",
+    "Given an asset and recent feedback events about it, produce a single",
+    "concise *lesson* an agent should remember next time it works on this",
+    "asset's domain.",
+    "",
+    "Output MUST be a complete markdown file with YAML frontmatter:",
+    "  ---",
+    "  description: <one-line summary of what the lesson teaches>",
+    "  when_to_use: <one-line trigger that should make a caller apply it>",
+    "  ---",
+    "",
+    "  <lesson body, plain markdown, 1–3 short paragraphs>",
+    "",
+    "Both `description` and `when_to_use` MUST be non-empty single-line strings.",
+    "Output ONLY the lesson file contents — no prose, no fences, no preamble.",
+].join("\n");
+/** Pure: build the user-prompt body. Exported for tests. */
+export function buildDistillPrompt(input) {
+    const lines = [];
+    lines.push(`Asset ref: ${input.inputRef}`);
+    lines.push("");
+    lines.push("Asset content:");
+    if (input.assetContent) {
+        lines.push("```");
+        lines.push(input.assetContent.trim());
+        lines.push("```");
+    }
+    else {
+        lines.push("(asset is not currently indexed; distil from feedback signal alone)");
+    }
+    lines.push("");
+    lines.push("Recent feedback events (most recent last):");
+    if (input.feedback.length === 0) {
+        lines.push("(no feedback events recorded — distil from the asset itself)");
+    }
+    else {
+        for (const event of input.feedback) {
+            const meta = event.metadata ? ` ${JSON.stringify(event.metadata)}` : "";
+            lines.push(`- ${event.ts} ${event.eventType}${meta}`);
+        }
+    }
+    lines.push("");
+    lines.push("Produce the lesson markdown file now.");
+    return lines.join("\n");
+}
+// ── Main entry point ────────────────────────────────────────────────────────
+/**
+ * Run a single bounded distillation pass for `ref`. Always emits exactly one
+ * `distill_invoked` event (with `outcome` in the metadata) regardless of the
+ * branch taken — so observers can count invocations cheaply.
+ */
+export async function akmDistill(options) {
+    const inputRef = options.ref.trim();
+    if (!inputRef) {
+        throw new UsageError("Asset ref is required. Usage: akm distill <ref>", "MISSING_REQUIRED_ARGUMENT");
+    }
+    // Validate the ref shape up front so a typo never reaches the LLM.
+    parseAssetRef(inputRef);
+    const lessonRef = deriveLessonRef(inputRef);
+    const config = options.config ?? loadConfig();
+    const stash = options.stashDir ?? resolveStashDir();
+    const chat = options.chat ?? chatCompletion;
+    const lookup = options.lookupFn ?? defaultLookup;
+    const readEventsImpl = options.readEventsFn ?? readEvents;
+    // Best-effort load: when the asset is not yet indexed we still proceed —
+    // the LLM is asked to distil from "available signal" (feedback alone).
+    let assetContent = null;
+    try {
+        const filePath = await lookup(inputRef);
+        if (filePath && fs.existsSync(filePath)) {
+            assetContent = fs.readFileSync(filePath, "utf8");
+        }
+    }
+    catch {
+        assetContent = null;
+    }
+    const { events } = readEventsImpl({ ref: inputRef, type: "feedback" });
+    // #267 — feedback exclusion. Filter events whose `ref` matches the
+    // exclusion list BEFORE the prompt is built. The original event stream
+    // is never mutated; only the `feedback` slice that reaches the LLM is
+    // affected. The exclusion set is normalised through `parseAssetRef` →
+    // re-serialised so callers can pass canonical or origin-prefixed refs
+    // and the comparison still works against the event payload's `ref`.
+    const exclusionList = options.excludeFeedbackFromRefs ?? [];
+    const exclusionSet = new Set(exclusionList.map((ref) => ref.trim()).filter((ref) => ref.length > 0));
+    const originalEventCount = events.length;
+    const filteredEvents = exclusionSet.size > 0 ? events.filter((e) => !(e.ref !== undefined && exclusionSet.has(e.ref))) : events;
+    const filteredFeedbackCount = originalEventCount - filteredEvents.length;
+    const feedbackFullyFiltered = exclusionSet.size > 0 && originalEventCount > 0 && filteredEvents.length === 0;
+    const feedback = filteredEvents.slice(-20).map((e) => ({
+        ts: e.ts,
+        eventType: e.eventType,
+        ...(e.metadata !== undefined ? { metadata: e.metadata } : {}),
+    }));
+    const userPrompt = buildDistillPrompt({ inputRef, assetContent, feedback });
+    const messages = [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: userPrompt },
+    ];
+    // Single bounded LLM call. The wrapper handles the gate-check, 30 s
+    // timeout, and error fallback (returning `null`).
+    const raw = await tryLlmFeature("feedback_distillation", config, async () => {
+        if (!config.llm) {
+            // No LLM connection configured — treat as gate-disabled. Throwing
+            // here lets `tryLlmFeature` route us through the "error" fallback,
+            // which is the same graceful skipped path.
+            throw new ConfigError("No LLM connection configured. Set `llm.endpoint` and `llm.model` in the akm config.", "LLM_NOT_CONFIGURED");
+        }
+        return chat(config.llm, messages);
+    }, null);
+    if (raw === null || raw.trim() === "") {
+        appendEvent({
+            eventType: "distill_invoked",
+            ref: inputRef,
+            metadata: {
+                outcome: "skipped",
+                lessonRef,
+                ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+            },
+        });
+        return {
+            schemaVersion: 1,
+            ok: true,
+            outcome: "skipped",
+            inputRef,
+            lessonRef,
+            message: "feedback distillation is disabled or the LLM call failed; no proposal created.",
+            ...(exclusionSet.size > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {}),
+        };
+    }
+    // Strip any stray fence the LLM might have added around the markdown.
+    const content = stripMarkdownFences(raw);
+    // Parse + lint the lesson before creating the proposal. The lint is the
+    // canonical gate for required frontmatter (v1 spec §13). On failure we
+    // surface a structured error and exit non-zero — but still emit
+    // `distill_invoked` so the failure is observable.
+    const lintReport = lintLessonContent(content, `distill:${inputRef}`);
+    if (lintReport.findings.length > 0) {
+        appendEvent({
+            eventType: "distill_invoked",
+            ref: inputRef,
+            metadata: {
+                outcome: "validation_failed",
+                lessonRef,
+                findingKinds: lintReport.findings.map((f) => f.kind),
+                ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+            },
+        });
+        const message = lintReport.findings.map((f) => f.message).join("\n");
+        throw new UsageError(`Distilled lesson failed validation:\n${message}`, "MISSING_REQUIRED_ARGUMENT", "Lessons require non-empty `description` and `when_to_use` frontmatter fields. See v1 spec §13.");
+    }
+    // Round-trip the parsed frontmatter so the proposal carries it as a
+    // structured payload alongside the raw content (matches the shape used by
+    // other proposal sources).
+    const parsed = parseFrontmatter(content);
+    const proposal = createProposal(stash, {
+        ref: lessonRef,
+        source: "distill",
+        ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
+        payload: {
+            content,
+            ...(Object.keys(parsed.data).length > 0 ? { frontmatter: parsed.data } : {}),
+        },
+    }, options.ctx);
+    appendEvent({
+        eventType: "distill_invoked",
+        ref: inputRef,
+        metadata: {
+            outcome: "queued",
+            lessonRef,
+            proposalId: proposal.id,
+            ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
+            ...(exclusionSet.size > 0 ? { filteredFeedbackCount } : {}),
+        },
+    });
+    return {
+        schemaVersion: 1,
+        ok: true,
+        outcome: "queued",
+        inputRef,
+        lessonRef,
+        proposalId: proposal.id,
+        proposal,
+        ...(exclusionSet.size > 0 ? { filteredFeedbackCount, feedbackFullyFiltered } : {}),
+    };
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+async function defaultLookup(ref) {
+    try {
+        const entry = await indexerLookup(parseAssetRef(ref));
+        return entry?.filePath ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Best-effort fence stripping. Keeps the body intact when no fence is present. */
+function stripMarkdownFences(raw) {
+    const trimmed = raw.trim();
+    // Only strip outer triple-fence pairs — leave inner code blocks alone.
+    const fence = trimmed.match(/^```(?:markdown|md)?\s*\n([\s\S]*?)\n```\s*$/i);
+    if (fence)
+        return fence[1].trim();
+    return trimmed;
+}

package/dist/src/commands/events.js

@@ -0,0 +1,108 @@
+/**
+ * `akm events list` and `akm events tail` (#204).
+ *
+ * Programmatic surface — the CLI dispatcher in `src/cli.ts` registers two
+ * verbs that delegate here. Both return JSON envelopes shaped by
+ * `src/output/shapes.ts` so the output flows through the same shape and
+ * text-renderer pipeline as the rest of the CLI (no silent
+ * `JSON.stringify` fallback).
+ */
+import { parseAssetRef } from "../core/asset-ref";
+import { UsageError } from "../core/errors";
+import { readEvents, tailEvents } from "../core/events";
+/**
+ * Parse `--since` accepting either a byte-offset cursor (`@offset:<int>`) for
+ * cross-process resumption, or a timestamp / epoch-ms (the existing form).
+ * Returns one of `{ sinceOffset }` or `{ since }`.
+ */
+function parseSinceFlag(since) {
+    if (since === undefined)
+        return {};
+    const trimmed = since.trim();
+    if (!trimmed) {
+        throw new UsageError("--since cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    if (trimmed.startsWith("@offset:")) {
+        const raw = trimmed.slice("@offset:".length);
+        const value = Number.parseInt(raw, 10);
+        if (Number.isNaN(value) || value < 0) {
+            throw new UsageError(`Invalid --since byte offset: "${since}". Expected @offset:<non-negative integer>.`, "INVALID_FLAG_VALUE");
+        }
+        return { sinceOffset: value };
+    }
+    return { since: normalizeSince(trimmed) };
+}
+function validateRef(ref) {
+    if (ref === undefined)
+        return undefined;
+    const trimmed = ref.trim();
+    if (!trimmed) {
+        throw new UsageError("--ref cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    parseAssetRef(trimmed);
+    return trimmed;
+}
+function normalizeSince(since) {
+    if (since === undefined)
+        return undefined;
+    const trimmed = since.trim();
+    if (!trimmed) {
+        throw new UsageError("--since cannot be empty.", "INVALID_FLAG_VALUE");
+    }
+    // Accept ISO timestamp (preferred), epoch ms, or plain date.
+    if (/^\d+$/.test(trimmed)) {
+        const ms = Number.parseInt(trimmed, 10);
+        const d = new Date(ms);
+        if (Number.isNaN(d.getTime())) {
+            throw new UsageError(`Invalid --since value: ${since}`, "INVALID_FLAG_VALUE");
+        }
+        return d.toISOString();
+    }
+    const parsed = new Date(trimmed);
+    if (Number.isNaN(parsed.getTime())) {
+        throw new UsageError(`Invalid --since value: ${since}. Expected ISO timestamp (e.g. 2026-04-01T00:00:00Z) or epoch ms.`, "INVALID_FLAG_VALUE");
+    }
+    return parsed.toISOString();
+}
+export function akmEventsList(options = {}) {
+    const ref = validateRef(options.ref);
+    const parsed = parseSinceFlag(options.since);
+    const result = readEvents({ since: parsed.since, sinceOffset: parsed.sinceOffset, type: options.type, ref }, options.ctx);
+    return {
+        schemaVersion: 1,
+        totalCount: result.events.length,
+        ...(ref !== undefined ? { ref } : {}),
+        ...(options.type !== undefined ? { type: options.type } : {}),
+        ...(parsed.since !== undefined ? { since: parsed.since } : {}),
+        ...(parsed.sinceOffset !== undefined ? { sinceOffset: parsed.sinceOffset } : {}),
+        nextOffset: result.nextOffset,
+        events: result.events,
+    };
+}
+export async function akmEventsTail(options = {}) {
+    const ref = validateRef(options.ref);
+    const parsed = parseSinceFlag(options.since);
+    const tailOptions = {
+        since: parsed.since,
+        sinceOffset: parsed.sinceOffset,
+        type: options.type,
+        ref,
+        intervalMs: options.intervalMs,
+        maxDurationMs: options.maxDurationMs,
+        maxEvents: options.maxEvents,
+        signal: options.signal,
+        onEvent: options.onEvent,
+    };
+    const result = await tailEvents(tailOptions, options.ctx);
+    return {
+        schemaVersion: 1,
+        totalCount: result.events.length,
+        ...(ref !== undefined ? { ref } : {}),
+        ...(options.type !== undefined ? { type: options.type } : {}),
+        ...(parsed.since !== undefined ? { since: parsed.since } : {}),
+        ...(parsed.sinceOffset !== undefined ? { sinceOffset: parsed.sinceOffset } : {}),
+        nextOffset: result.nextOffset,
+        events: result.events,
+        reason: result.reason,
+    };
+}