akm-cli 0.6.1 → 0.7.0

package/dist/src/llm/feature-gate.js

@@ -0,0 +1,108 @@
+/**
+ * Per-feature LLM gates (v1 spec §14).
+ *
+ * Every bounded in-tree LLM call site in akm is addressed by exactly one
+ * feature key under `llm.features.*`. This module is the single seam call
+ * sites use to ask "should I run?" and "if I run and fail, what do I return?"
+ *
+ * The seam is intentionally tiny:
+ *
+ *   - `isLlmFeatureEnabled(config, feature)` — pure predicate, no side
+ *     effects, no I/O. Returns `true` only when the feature flag is the
+ *     literal boolean `true` in config. Defaults are `false` per v1
+ *     spec §14 — adding a flag to the schema is a non-event until the user
+ *     opts in.
+ *   - `tryLlmFeature(feature, config, fn, fallback, opts?)` — single-call
+ *     wrapper that runs `fn()` only when the gate is open, enforces a hard
+ *     timeout (default 30s — overridable per call), and returns `fallback`
+ *     on disablement, throw, or timeout. The wrapper is referentially
+ *     transparent for any given (gate-state, fn-result) pair: no module
+ *     state is mutated.
+ *
+ * Statelessness invariant (v1 spec §14.4): nothing in this module holds
+ * state across calls. There are no caches, no module-level singletons, no
+ * persistent connections. The architecture seam test
+ * (`tests/architecture/llm-stateless-seam.test.ts`) does not currently
+ * inspect this file but the same rule applies — keep all exports as pure
+ * functions.
+ */
+/**
+ * Pure predicate: is the named feature gate explicitly enabled in `config`?
+ *
+ * Returns `false` when:
+ *   - the LLM block is missing,
+ *   - the `features` block is missing,
+ *   - the key is absent (defaults are `false`),
+ *   - the key is set to `false`.
+ */
+export function isLlmFeatureEnabled(config, feature) {
+    if (!config?.llm?.features)
+        return false;
+    return config.llm.features[feature] === true;
+}
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Run `fn()` only if `isLlmFeatureEnabled(config, feature)` is `true`. On
+ * disablement, throw, or timeout, return `fallback` (or — if it is a
+ * thunk — the value produced by calling it).
+ *
+ * The fallback may be a value or a synchronous/async function returning a
+ * value. The thunk form lets call sites encode "run the deterministic
+ * pipeline" without paying for it in the success path:
+ *
+ * ```ts
+ * const ranked = await tryLlmFeature(
+ *   "curate_rerank",
+ *   config,
+ *   () => llmRerank(candidates),
+ *   () => deterministicRerank(candidates),
+ * );
+ * ```
+ */
+export async function tryLlmFeature(feature, config, fn, fallback, opts) {
+    const resolveFallback = async () => typeof fallback === "function" ? await fallback() : fallback;
+    if (!isLlmFeatureEnabled(config, feature)) {
+        opts?.onFallback?.({ feature, reason: "disabled" });
+        return resolveFallback();
+    }
+    const timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    try {
+        if (timeoutMs <= 0) {
+            return await fn();
+        }
+        return await runWithTimeout(fn, timeoutMs, feature);
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        const reason = error instanceof LlmFeatureTimeoutError ? "timeout" : "error";
+        opts?.onFallback?.({ feature, reason, error });
+        return resolveFallback();
+    }
+}
+/** Specific error class so call sites and the wrapper can tell timeouts apart from generic throws. */
+export class LlmFeatureTimeoutError extends Error {
+    feature;
+    timeoutMs;
+    constructor(feature, timeoutMs) {
+        super(`LLM feature "${feature}" timed out after ${timeoutMs}ms.`);
+        this.name = "LlmFeatureTimeoutError";
+        this.feature = feature;
+        this.timeoutMs = timeoutMs;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+async function runWithTimeout(fn, timeoutMs, feature) {
+    let timer;
+    try {
+        return await new Promise((resolve, reject) => {
+            timer = setTimeout(() => reject(new LlmFeatureTimeoutError(feature, timeoutMs)), timeoutMs);
+            Promise.resolve()
+                .then(() => fn())
+                .then(resolve, reject);
+        });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/src/llm/graph-extract.js

@@ -0,0 +1,107 @@
+/**
+ * LLM helper for the `akm index` graph-extraction pass (#207).
+ *
+ * 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
+ * files to extract, persisting the resulting nodes/edges to a stash-local
+ * `graph.json` artifact, and feeding the artifact into the FTS5+boosts
+ * search pipeline as a single boost component.
+ *
+ * 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
+ * shared `akm.llm` block — never from a per-pass override. Callers obtain
+ * the connection via `resolveIndexPassLLM("graph", config)` and pass it
+ * straight through.
+ */
+import { toErrorMessage } from "../core/common";
+import { warn } from "../core/warn";
+import { chatCompletion, parseJsonResponse } from "./client";
+/** Hard cap on body chars sent to the model. */
+const MAX_BODY_CHARS = 4000;
+/** Hard cap on entities returned per asset — guards against runaway LLM output. */
+const MAX_ENTITIES_PER_ASSET = 32;
+/** Hard cap on relations returned per asset. */
+const MAX_RELATIONS_PER_ASSET = 32;
+/** Hard timeout for the LLM call; an `akm index` run must not hang on a misbehaving endpoint. */
+const LLM_TIMEOUT_MS = 30_000;
+const SYSTEM_PROMPT = "You extract a knowledge graph from developer notes. Return only valid JSON. " + "No prose, no markdown fences.";
+const USER_PROMPT_PREFIX = `Extract entities and relations from the asset body below.
+
+Rules:
+- Output ONLY a JSON object: {"entities": ["Entity One", ...], "relations": [{"from": "A", "to": "B", "type": "uses"}, ...]}.
+- Entities are short, canonical noun phrases (project names, services, tools, people, file/dir names, technical concepts).
+- Relations connect two entities that both appear in the entities array.
+- "type" is a short verb phrase (e.g. "uses", "depends on", "owns", "documents"). Optional; omit when unsure.
+- Drop pleasantries, meta-commentary, and timestamps.
+- Limit to at most ${MAX_ENTITIES_PER_ASSET} entities and ${MAX_RELATIONS_PER_ASSET} relations per asset.
+- Return {"entities": [], "relations": []} if the body has no extractable graph content.
+
+Asset body:
+`;
+/**
+ * Extract entities and relations from a single asset body via the configured LLM.
+ *
+ * Returns `{entities: [], relations: []}` on any failure (timeout, invalid
+ * JSON, empty response). Errors are logged via `warn()` but never thrown — a
+ * failed extraction for one asset must not abort the rest of the index pass.
+ */
+export async function extractGraphFromBody(llmConfig, body) {
+    const empty = { entities: [], relations: [] };
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return empty;
+    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
+    let timeoutHandle;
+    try {
+        const raw = await Promise.race([
+            chatCompletion(llmConfig, [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userPrompt },
+            ], { maxTokens: 1024, temperature: 0.1 }),
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error("graph extraction timed out")), LLM_TIMEOUT_MS);
+            }),
+        ]);
+        if (!raw)
+            return empty;
+        const parsed = parseJsonResponse(raw);
+        if (!parsed) {
+            warn("graph extraction: invalid JSON response from LLM; skipping asset.");
+            return empty;
+        }
+        const entities = Array.isArray(parsed.entities)
+            ? parsed.entities
+                .filter((e) => typeof e === "string")
+                .map((e) => e.trim())
+                .filter((e) => e.length > 0)
+                .slice(0, MAX_ENTITIES_PER_ASSET)
+            : [];
+        const entitySet = new Set(entities);
+        const relations = Array.isArray(parsed.relations)
+            ? parsed.relations
+                .filter((r) => typeof r === "object" && r !== null && !Array.isArray(r))
+                .map((r) => ({
+                from: typeof r.from === "string" ? r.from.trim() : "",
+                to: typeof r.to === "string" ? r.to.trim() : "",
+                type: typeof r.type === "string" && r.type.trim() ? r.type.trim() : undefined,
+            }))
+                // Both endpoints must be non-empty AND mentioned in entities[];
+                // dangling relations are noise and inflate the boost component.
+                .filter((r) => r.from && r.to && entitySet.has(r.from) && entitySet.has(r.to))
+                .slice(0, MAX_RELATIONS_PER_ASSET)
+            : [];
+        return { entities, relations };
+    }
+    catch (err) {
+        warn(`graph extraction failed: ${toErrorMessage(err)}`);
+        return empty;
+    }
+    finally {
+        if (timeoutHandle !== undefined)
+            clearTimeout(timeoutHandle);
+    }
+}

package/dist/src/llm/index-passes.js

@@ -0,0 +1,35 @@
+/**
+ * Per-pass LLM config resolution for `akm index`.
+ *
+ * Locked v1 contract (#208):
+ * - There is exactly one provider/model configuration: `akm.llm`.
+ * - Every LLM-using pass inside `akm index` defaults to that block.
+ * - A pass can be opted out individually with `index.<passName>.llm = false`.
+ * - Any attempt to supply provider/model fields under `index.<passName>` is
+ *   rejected at config-load time by `parseIndexConfig` in
+ *   {@link ../core/config.ts} (`ConfigError("INVALID_CONFIG_FILE")`).
+ *
+ * Passes plug in by calling {@link resolveIndexPassLLM} with their pass
+ * name (e.g. `"memory"` for #201's memory-inference pass, `"graph"` for
+ * #207's graph-extraction pass). They do not read `config.llm` directly.
+ * This keeps the config surface small and the wiring uniform.
+ */
+/**
+ * Resolve the {@link LlmConnectionConfig} a single index pass should use, or
+ * `undefined` when the pass should run without an LLM.
+ *
+ * Returns `undefined` if any of:
+ * - No top-level `akm.llm` block is configured.
+ * - The pass is explicitly opted out (`index.<passName>.llm === false`).
+ *
+ * Otherwise returns the shared `akm.llm` config. There is no per-pass
+ * provider override; that decision is locked by §9 of the v1 spec.
+ */
+export function resolveIndexPassLLM(passName, config) {
+    if (!config.llm)
+        return undefined;
+    const passConfig = config.index?.[passName];
+    if (passConfig?.llm === false)
+        return undefined;
+    return config.llm;
+}

package/dist/src/llm/memory-infer.js

@@ -0,0 +1,86 @@
+/**
+ * LLM helper for the `akm index` memory-inference pass (#201).
+ *
+ * Splits a single memory body into a list of atomic facts. The pass itself
+ * (in `src/indexer/memory-inference.ts`) is responsible for deciding which
+ * memories are pending, persisting the resulting atomic memories 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.
+ *
+ * Locked v1 contract (#208): the LLM connection always comes from the
+ * shared `akm.llm` block — never from a per-pass override. Callers obtain
+ * the connection via `resolveIndexPassLLM("memory", config)` and pass it
+ * straight through.
+ */
+import { toErrorMessage } from "../core/common";
+import { warn } from "../core/warn";
+import { chatCompletion, parseJsonResponse } from "./client";
+/** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
+const MAX_BODY_CHARS = 4000;
+/** Hard cap on the number of atomic facts returned per memory. */
+const MAX_FACTS_PER_MEMORY = 16;
+/** Hard timeout for the LLM call. The index run must not hang on a misbehaving endpoint. */
+const LLM_TIMEOUT_MS = 30_000;
+const SYSTEM_PROMPT = "You split a developer memory into atomic, self-contained facts. " +
+    "Return only valid JSON. No prose, no markdown fences.";
+const USER_PROMPT_PREFIX = `Split the memory below into a JSON array of short, self-contained atomic facts.
+
+Rules:
+- Output ONLY a JSON object: {"facts": ["fact one", "fact two", ...]}.
+- Each fact is a single complete sentence, decontextualized so it stands alone.
+- Drop pleasantries, meta-commentary, and timestamps.
+- Preserve technical specifics (names, versions, identifiers) verbatim.
+- If the memory is already a single atomic fact, return it as the only entry.
+- Limit to at most ${MAX_FACTS_PER_MEMORY} facts.
+
+Memory:
+`;
+/**
+ * Split a single memory body into atomic facts via the configured LLM.
+ *
+ * Returns `[]` 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.
+ */
+export async function splitMemoryIntoAtomicFacts(llmConfig, body) {
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return [];
+    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
+    let timeoutHandle;
+    try {
+        const raw = await Promise.race([
+            chatCompletion(llmConfig, [
+                { role: "system", content: SYSTEM_PROMPT },
+                { role: "user", content: userPrompt },
+            ], { maxTokens: 768, temperature: 0.1 }),
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new Error("memory inference timed out")), LLM_TIMEOUT_MS);
+            }),
+        ]);
+        if (!raw)
+            return [];
+        const parsed = parseJsonResponse(raw);
+        if (!parsed || !Array.isArray(parsed.facts)) {
+            warn("memory inference: invalid JSON response from LLM; skipping memory.");
+            return [];
+        }
+        const facts = parsed.facts
+            .filter((f) => typeof f === "string")
+            .map((f) => f.trim())
+            .filter((f) => f.length > 0)
+            .slice(0, MAX_FACTS_PER_MEMORY);
+        return facts;
+    }
+    catch (err) {
+        warn(`memory inference failed: ${toErrorMessage(err)}`);
+        return [];
+    }
+    finally {
+        if (timeoutHandle !== undefined)
+            clearTimeout(timeoutHandle);
+    }
+}

package/dist/{output → src/output}/cli-hints.js

@@ -11,6 +11,19 @@ const EMBEDDED_HINTS = `# akm CLI
 
 You have access to a searchable library of scripts, skills, commands, agents, knowledge documents, workflows, wikis, and memories via \`akm\`. Search your sources first before writing something from scratch.
 
+## Agent Task Loop
+
+For any task, follow this loop:
+1. \`akm curate "<task>"\` — find the best matching asset
+2. \`akm show <ref>\` — read the schema (field names and structure)
+3. Edit the workspace file using schema field names + task-specific values from your README
+4. \`akm feedback <ref> --positive\` — record success
+
+For workflow tasks:
+1. \`akm workflow next workflow:<name>\` — get current step instructions
+2. Do the step work in your workspace
+3. \`akm workflow complete <run-id> --step <step-id>\` — mark done, get next step
+
 ## Quick Reference
 
 \`\`\`sh
@@ -144,7 +157,7 @@ akm wiki list                                  # List wikis (name, pages, raws,
 akm wiki create research                       # Scaffold a new wiki
 akm wiki register ics-docs ~/code/ics-documentation # Register an external wiki
 akm wiki show research                         # Path, description, counts, last 3 log entries
-akm wiki pages research                        # Page refs + descriptions (excludes schema/index/log/raw)
+akm wiki pages research                        # Page refs + descriptions (excludes schema/index/log; includes raw/)
 akm wiki search research "attention"           # Scoped search (equivalent to --type wiki --wiki research)
 akm wiki stash research ./paper.md             # Copy source into raw/<slug>.md (never overwrites)
 echo "..." | akm wiki stash research -         # stdin form
@@ -254,7 +267,7 @@ akm registry add <url> --provider skills-sh   # Specify provider type
 akm registry remove <url-or-name>             # Remove a registry
 akm registry search "<query>"                 # Search all registries
 akm registry search "<query>" --assets        # Include asset-level results
-akm registry build-index                      # Build ./index.json
+akm registry build-index                      # Build the default cache-backed index.json
 akm registry build-index --out dist/index.json # Build to a custom path
 \`\`\`
 

package/dist/{output → src/output}/renderers.js

@@ -187,12 +187,14 @@ const skillMdRenderer = {
     name: "skill-md",
     buildShowResponse(ctx) {
         const name = deriveName(ctx);
+        const parsed = parseFrontmatter(ctx.content());
         return {
             type: "skill",
             name,
             path: ctx.absPath,
             action: "Read and follow the instructions below",
-            content: ctx.content(),
+            description: toStringOrUndefined(parsed.data.description),
+            content: parsed.content,
         };
     },
 };
@@ -391,6 +393,64 @@ const wikiMdRenderer = {
         }
     },
 };
+// ── 4c. lesson-md ────────────────────────────────────────────────────────────
+/**
+ * Renderer for the `lesson` asset type (v1 spec §13).
+ *
+ * Lessons are markdown files with required `description` and `when_to_use`
+ * frontmatter. The renderer projects both fields explicitly so consumers can
+ * decide whether to apply a lesson without reading the full body. Lint
+ * (see `src/core/lesson-lint.ts`) is the contract enforcer; the renderer is
+ * intentionally tolerant — a lesson missing required fields will still render
+ * its body so the user has something to work with while they fix the file.
+ */
+const lessonMdRenderer = {
+    name: "lesson-md",
+    buildShowResponse(ctx) {
+        const name = deriveName(ctx);
+        const parsed = parseFrontmatter(ctx.content());
+        const description = toStringOrUndefined(parsed.data.description);
+        const whenToUse = toStringOrUndefined(parsed.data.when_to_use);
+        const action = whenToUse
+            ? `Apply this lesson when: ${whenToUse}`
+            : "Apply this lesson when its `when_to_use` trigger matches the current task.";
+        return {
+            type: "lesson",
+            name,
+            path: ctx.absPath,
+            action,
+            description,
+            content: parsed.content,
+        };
+    },
+    extractMetadata(entry, ctx) {
+        try {
+            const parsed = parseFrontmatter(ctx.content());
+            const fm = parsed.data;
+            const desc = toStringOrUndefined(fm.description);
+            if (desc && !entry.description) {
+                entry.description = desc;
+                entry.source = "frontmatter";
+                entry.confidence = 0.9;
+            }
+            const whenToUse = toStringOrUndefined(fm.when_to_use);
+            if (whenToUse) {
+                const hints = new Set(entry.searchHints ?? []);
+                hints.add(`when_to_use:${whenToUse}`);
+                entry.searchHints = Array.from(hints).filter(Boolean);
+            }
+            if (Array.isArray(fm.tags) && fm.tags.length > 0) {
+                const fmTags = fm.tags.filter((t) => typeof t === "string" && t.trim().length > 0);
+                if (fmTags.length > 0) {
+                    entry.tags = Array.from(new Set([...(entry.tags ?? []), ...fmTags]));
+                }
+            }
+        }
+        catch {
+            // Non-fatal: skip metadata extraction on parse error
+        }
+    },
+};
 // ── 5. memory-md ─────────────────────────────────────────────────────────────
 const memoryMdRenderer = {
     name: "memory-md",
@@ -560,6 +620,7 @@ const builtinRenderers = [
     agentMdRenderer,
     knowledgeMdRenderer,
     wikiMdRenderer,
+    lessonMdRenderer,
     memoryMdRenderer,
     workflowMdRenderer,
     scriptSourceRenderer,
@@ -575,4 +636,4 @@ export function registerBuiltinRenderers() {
     }
 }
 // ── Named exports for testing ────────────────────────────────────────────────
-export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, vaultEnvRenderer, wikiMdRenderer, workflowMdRenderer, };
+export { agentMdRenderer, commandMdRenderer, INTERPRETER_MAP, knowledgeMdRenderer, lessonMdRenderer, memoryMdRenderer, SETUP_SIGNALS, scriptSourceRenderer, skillMdRenderer, vaultEnvRenderer, wikiMdRenderer, workflowMdRenderer, };