akm-cli 0.7.4 → 0.8.0-rc.10

package/dist/llm/index-passes.js

@@ -1,35 +1,50 @@
+// 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 { getDefaultLlmConfig, getIndexPassConfig } from "../core/config";
 /**
- * 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.
+ * Map a pass name (as used by callers — "memory", "graph", etc.) to the
+ * matching key under `profiles.improve.default.processes`. Pass names with
+ * no improve-profile counterpart return undefined and resolve via the
+ * default LLM only.
  */
+function improveProcessKeyForPass(passName) {
+    switch (passName) {
+        case "memory":
+            return "memoryInference";
+        case "graph":
+            return "graphExtraction";
+        default:
+            return undefined;
+    }
+}
 export function resolveIndexPassLLM(passName, config) {
-    if (!config.llm)
-        return undefined;
-    const passConfig = config.index?.[passName];
+    // Gate 1 — explicit opt-out via the index-config block stays authoritative.
+    const passConfig = getIndexPassConfig(config.index, passName);
     if (passConfig?.llm === false)
         return undefined;
-    return config.llm;
+    // Gate 2 — per-process profile from the improve profile, when present.
+    // This is the path that lets
+    //   profiles.improve.default.processes.graphExtraction.profile = "ministral-3b"
+    // actually take effect on the graph pass instead of being silently
+    // ignored.
+    const processKey = improveProcessKeyForPass(passName);
+    if (processKey) {
+        const processConfig = config.profiles?.improve?.default?.processes?.[processKey];
+        // Honor enabled === false here too — an explicit disable wins.
+        if (processConfig?.enabled === false)
+            return undefined;
+        const profileName = processConfig?.profile;
+        if (profileName) {
+            const profile = config.profiles?.llm?.[profileName];
+            if (profile)
+                return profile;
+            // A named-but-missing profile is a configuration error in spirit, but
+            // we fall through to default rather than throwing — callers gracefully
+            // treat `undefined` as "pass disabled" and emitting a hard throw here
+            // would take the whole improve run down on a typo.
+        }
+    }
+    // Gate 3 — fall back to the default LLM profile.
+    return getDefaultLlmConfig(config);
 }

package/dist/llm/memory-infer.js

@@ -1,3 +1,6 @@
+// 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 helper for the `akm index` memory-inference pass (#201).
  *
@@ -18,97 +21,103 @@
 import { toErrorMessage } from "../core/common";
 import { warn } from "../core/warn";
 import { chatCompletion, parseEmbeddedJsonResponse } from "./client";
+import { tryLlmFeature } from "./feature-gate";
 /** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
 const MAX_BODY_CHARS = 4000;
-/** 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 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 concise, information-dense derived memory.
-
-Rules:
-- Output ONLY a JSON object with exactly these keys: {"title": string, "description": string, "tags": string[], "searchHints": string[], "content": string}.
-- ` +
-    '"title"' +
-    ` is a short, descriptive title for the derived memory.
-- ` +
-    '"description"' +
-    ` is one sentence explaining why this derived memory matters.
-- ` +
-    '"tags"' +
-    ` contains 3-8 specific keywords.
-- ` +
-    '"searchHints"' +
-    ` contains 3-6 natural-language retrieval phrases.
-- ` +
-    '"content"' +
-    ` must be compact markdown that preserves the reusable insight, root cause, fix, constraints, and applicability conditions when present.
-- Prefer 2-4 short sections with informative headings over long prose.
-- Omit timestamps, verification-only metrics, pleasantries, and session-specific chatter unless they are essential to applying the insight later.
-- Preserve technical specifics (names, versions, identifiers, selectors, file paths, config keys) verbatim.
+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:
 `;
+/**
+ * Strict JSON Schema for the derived-memory payload. Sent to providers that
+ * opt in via `LlmConnectionConfig.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
+ * 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 `tryLlmFeature("memory_inference", ...)` so the feature gate
+ * and onFallback hook are honoured uniformly (Fix C5).
  */
-export async function compressMemoryToDerivedMemory(llmConfig, body, signal) {
+export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback) {
     const trimmedBody = body.trim();
     if (!trimmedBody)
         return undefined;
     const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
-    let timeoutHandle;
-    try {
-        const raw = await Promise.race([
-            chatCompletion(llmConfig, [
+    return tryLlmFeature("memory_inference", akmConfig, async () => {
+        try {
+            const raw = await chatCompletion(llmConfig, [
                 { role: "system", content: SYSTEM_PROMPT },
                 { role: "user", content: userPrompt },
-            ], { maxTokens: 768, temperature: 0.1, signal }),
-            new Promise((_, reject) => {
-                timeoutHandle = setTimeout(() => reject(new Error("memory inference timed out")), LLM_TIMEOUT_MS);
-            }),
-        ]);
-        if (!raw)
-            return undefined;
-        const parsed = parseEmbeddedJsonResponse(raw);
-        if (!parsed) {
-            warn("memory inference: invalid JSON response from LLM; skipping memory.");
-            return undefined;
+            ], {
+                temperature: 0.1,
+                timeoutMs: llmConfig.timeoutMs,
+                signal,
+                responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
+            });
+            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;
+            }
+            return { title, description, tags, searchHints, content };
         }
-        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.");
+        catch (err) {
+            warn(`memory inference failed: ${toErrorMessage(err)}`);
             return undefined;
         }
-        return { title, description, tags, searchHints, content };
-    }
-    catch (err) {
-        warn(`memory inference failed: ${toErrorMessage(err)}`);
-        return undefined;
-    }
-    finally {
-        if (timeoutHandle !== undefined)
-            clearTimeout(timeoutHandle);
-    }
+    }, undefined, {
+        timeoutMs: llmConfig.timeoutMs,
+        onFallback,
+    });
 }

package/dist/llm/metadata-enhance.js

@@ -1,25 +1,28 @@
-/**
- * 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`.
- */
+// 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, parseJsonResponse } from "./client";
+import { tryLlmFeature } from "./feature-gate";
 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.`;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,
  * generate searchHints, and suggest tags.
+ *
+ * When `akmConfig` is provided, routes through
+ * `tryLlmFeature("metadata_enhance", ...)` so the feature gate is honoured and
+ * errors are swallowed to `{}`. 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).
  */
-export async function enhanceMetadata(config, entry, fileContent, signal) {
+export async function enhanceMetadata(config, entry, fileContent, signal, akmConfig) {
     const contextParts = [`Name: ${entry.name}`, `Type: ${entry.type}`];
     if (entry.description)
         contextParts.push(`Current description: ${entry.description}`);
     if (entry.tags?.length)
         contextParts.push(`Current tags: ${entry.tags.join(", ")}`);
     if (fileContent) {
-        // Limit content to first 2000 chars to stay within token limits
-        const truncated = fileContent.length > 2000 ? `${fileContent.slice(0, 2000)}\n... (truncated)` : fileContent;
+        // Limit content to first 4000 chars to stay within token limits (matches other modules)
+        const truncated = fileContent.length > 4000 ? `${fileContent.slice(0, 4000)}\n... (truncated)` : fileContent;
         contextParts.push(`File content:\n${truncated}`);
     }
     const userPrompt = `${contextParts.join("\n")}
@@ -30,24 +33,34 @@ Generate improved metadata for this ${entry.type}. Return JSON with these fields
 - "tags": an array of 3-8 relevant keyword tags
 
 Return ONLY the JSON object, no explanation.`;
-    const raw = await chatCompletion(config, [
-        { role: "system", content: SYSTEM_PROMPT },
-        { role: "user", content: userPrompt },
-    ], { signal });
-    const parsed = parseJsonResponse(raw);
-    if (!parsed)
-        return {};
-    const result = {};
-    if (typeof parsed.description === "string" && parsed.description) {
-        result.description = parsed.description;
-    }
-    if (Array.isArray(parsed.searchHints)) {
-        result.searchHints = parsed.searchHints
-            .filter((s) => typeof s === "string" && s.trim().length > 0)
-            .slice(0, 8);
-    }
-    if (Array.isArray(parsed.tags)) {
-        result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
+    const runLlm = async () => {
+        const raw = await chatCompletion(config, [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ], { signal });
+        const parsed = parseJsonResponse(raw);
+        if (!parsed)
+            return {};
+        const result = {};
+        if (typeof parsed.description === "string" && parsed.description) {
+            result.description = parsed.description;
+        }
+        if (Array.isArray(parsed.searchHints)) {
+            result.searchHints = parsed.searchHints
+                .filter((s) => typeof s === "string" && s.trim().length > 0)
+                .slice(0, 8);
+        }
+        if (Array.isArray(parsed.tags)) {
+            result.tags = parsed.tags.filter((s) => typeof s === "string" && s.trim().length > 0).slice(0, 10);
+        }
+        return result;
+    };
+    // When no akmConfig is provided, bypass the feature gate entirely: run the
+    // LLM call directly and let errors propagate to the caller (pre-gate
+    // behaviour). When akmConfig is present, honour the feature flag and swallow
+    // errors to {} via tryLlmFeature.
+    if (akmConfig === undefined) {
+        return runLlm();
     }
-    return result;
+    return tryLlmFeature("metadata_enhance", akmConfig, runLlm, {}, { timeoutMs: config.timeoutMs });
 }

package/dist/llm/prompts/extract-session.md

@@ -0,0 +1,80 @@
+You are extracting durable engineering insights from a software session transcript. Most sessions produce zero new durable insights — the agent already captures what's worth keeping via explicit `akm remember` / `akm feedback` calls during the session. Your job is to identify learnings that slipped through.
+
+## What counts as "durable insight"
+
+Things worth extracting:
+- Recovery patterns ("X fails when Y; the fix is Z")
+- Hidden constraints discovered mid-task ("this codebase requires X before deploy")
+- Architecture observations ("module A is consumed by B and C via the D bus")
+- Non-obvious workarounds for real defects
+- Domain knowledge the agent learned and would benefit a future session
+
+Things NOT to extract:
+- Successful command sequences (already in git history / shell history)
+- Tool counts / aggregates
+- The agent's own narrative about what it was doing
+- Restatements of what the user asked for
+- Generic platitudes ("test your code", "be careful with X")
+- Anything already preserved via the agent's explicit calls (see below)
+
+## Already preserved by the agent — DO NOT re-extract
+
+{{ALREADY_PRESERVED}}
+
+## Session metadata
+
+- Harness: {{HARNESS}}
+- Title: {{TITLE}}
+- Started: {{STARTED_AT}}
+- Ended: {{ENDED_AT}}
+- Project hint: {{PROJECT_HINT}}
+
+## Filtered session transcript
+
+The transcript below has already had read-only `akm` meta-ops and platform boilerplate stripped. Only content that might carry signal remains.
+
+{{TRANSCRIPT}}
+
+## Output contract
+
+Respond with EXACTLY one JSON object matching this shape:
+
+```
+{
+  "candidates": [
+    {
+      "type": "memory" | "lesson" | "knowledge",
+      "name": "<kebab-case-slug>",
+      "description": "<one sentence 20-400 chars>",
+      "when_to_use": "<one sentence 15-400 chars; REQUIRED only when type=lesson>",
+      "body": "<markdown body, 200-3000 chars typical>",
+      "confidence": <number 0.0-1.0>,
+      "evidence": "<one-line pointer to the moment in the session>"
+    }
+  ],
+  "rationale_if_empty": "<one sentence; REQUIRED when candidates is empty>"
+}
+```
+
+## Rules
+
+1. **Zero candidates is a valid and frequent answer.** Most sessions yield no new durable insight. When that's the case, return `{"candidates": [], "rationale_if_empty": "..."}` explaining what you saw and why it didn't rise to durable-knowledge level. Do not fabricate.
+
+2. **Pick the right type per candidate:**
+   - `memory` — a fact or short observation. Use for "X works on this codebase", "auth uses Y library version Z".
+   - `lesson` — a "do X / avoid Y" pattern, ALWAYS with `when_to_use`. Use for hard-won learnings about pitfalls, recovery patterns, or non-obvious gotchas.
+   - `knowledge` — substantive multi-section reference doc. Rare from one session.
+
+3. **Calibrate `confidence` honestly:**
+   - `0.9+` — high certainty this is a real durable insight a reviewer would clearly accept
+   - `0.7-0.89` — clear improvement, but a reviewer might prefer different framing or scope
+   - `0.5-0.69` — marginal / judgment call
+   - `<0.5` — don't include; prefer fewer-but-better candidates
+
+4. **`evidence` must reference the session** — a brief pointer like "agent's tool failure at ts=...", "user's correction at ...", "after the recovery in the Bash sequence around ...". Without evidence the candidate is hard to validate; default to lower confidence when evidence is vague.
+
+5. **Do not duplicate already-preserved content.** If a candidate substantively overlaps with anything in the "Already preserved" list above, skip it.
+
+6. **No speculation.** Only extract things the session genuinely demonstrates. If the agent struggled and didn't resolve, that may itself be a lesson (`when_to_use: "When attempting X, expect Y to fail"`) — but only if the failure mode is concrete enough to be useful next time.
+
+7. Respond with the JSON object only. No prose before or after. No code fences.

package/dist/llm/prompts/graph-extract-user-prompt.md

@@ -0,0 +1,35 @@
+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}} entities and {{MAX_RELATIONS}} relations per asset.
+- Return {"entities": [], "relations": []} if the body has no extractable graph content.
+- DO NOT return markdown code blocks, ONLY valid JSON objects.
+
+Examples:
+
+Input:
+## Deployment Notes
+The auth-service uses PostgreSQL for user sessions. It depends on the redis-cache
+for rate limiting. The terraform-provisioner deploys everything to the prod cluster.
+Owner: @alice.
+
+Output:
+{"entities":["auth-service","PostgreSQL","redis-cache","terraform-provisioner","prod cluster","@alice"],"relations":[{"from":"auth-service","to":"PostgreSQL","type":"uses"},{"from":"auth-service","to":"redis-cache","type":"depends on"},{"from":"terraform-provisioner","to":"prod cluster","type":"deploys"},{"from":"terraform-provisioner","to":"auth-service","type":"deploys"},{"from":"@alice","to":"auth-service","type":"owns"}]}
+
+Input:
+## Meeting: API Redesign
+Discussed moving from REST to GraphQL. The frontend team will use Apollo Client.
+Backend needs to implement resolvers. Timeline: Q2.
+
+Output:
+{"entities":["REST","GraphQL","Apollo Client","frontend team","backend","resolvers","Q2"],"relations":[{"from":"frontend team","to":"Apollo Client","type":"uses"},{"from":"backend","to":"resolvers","type":"implements"},{"from":"frontend team","to":"GraphQL","type":"migrates to"}]}
+
+===============
+
+Request:
+