akm-cli 0.7.5 → 0.8.0-rc1

package/dist/llm/graph-extract.js

@@ -5,8 +5,8 @@
  * 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
+ * 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.
  *
  * This module is intentionally tiny and stateless so tests can stub it via
@@ -20,86 +20,321 @@
 import { toErrorMessage } from "../core/common";
 import { warn } from "../core/warn";
 import { chatCompletion, parseEmbeddedJsonResponse } from "./client";
+import { tryLlmFeature } from "./feature-gate";
+import userPromptTemplate from "./prompts/graph-extract-user-prompt.md" with { type: "text" };
+/**
+ * Separator token used between assets in a batch prompt.
+ * Chosen to be visually clear and unlikely to appear verbatim in asset bodies.
+ */
+const BATCH_ASSET_SEPARATOR = "=== ASSET";
 /** 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;
-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:
-`;
+const SYSTEM_PROMPT = "You extract a knowledge graph from developer notes. Return ONLY valid JSON — no prose, no markdown fences, no preamble.";
+const USER_PROMPT_PREFIX = userPromptTemplate
+    .replace("{{MAX_ENTITIES}}", String(MAX_ENTITIES_PER_ASSET))
+    .replace("{{MAX_RELATIONS}}", String(MAX_RELATIONS_PER_ASSET));
+function parseConfidence(raw) {
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return undefined;
+    return Math.max(0, Math.min(1, raw));
+}
+function normalizeEntityName(raw) {
+    return raw
+        .trim()
+        .replace(/^[`"']+|[`"']+$/g, "")
+        .replace(/\s+/g, " ")
+        .replace(/[;,!?]+$/g, "")
+        .trim();
+}
+function normalizeRelationType(raw) {
+    const normalized = raw
+        .trim()
+        .toLowerCase()
+        .replace(/^[`"']+|[`"']+$/g, "")
+        .replace(/\s+/g, " ")
+        .replace(/[.;,!?]+$/g, "")
+        .trim();
+    if (!normalized)
+        return undefined;
+    if (normalized === "use" || normalized === "utilizes")
+        return "uses";
+    if (normalized === "depend on" || normalized === "depends")
+        return "depends on";
+    if (normalized === "integrates" || normalized === "integration with")
+        return "integrates with";
+    return normalized;
+}
+function parseGraphExtraction(raw) {
+    const empty = { entities: [], relations: [] };
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return empty;
+    const item = raw;
+    const entityCanonical = new Map();
+    if (Array.isArray(item.entities)) {
+        for (const value of item.entities) {
+            if (typeof value !== "string")
+                continue;
+            const normalized = normalizeEntityName(value);
+            if (!normalized)
+                continue;
+            const key = normalized.toLowerCase();
+            if (!entityCanonical.has(key))
+                entityCanonical.set(key, normalized);
+            if (entityCanonical.size >= MAX_ENTITIES_PER_ASSET)
+                break;
+        }
+    }
+    const entities = Array.from(entityCanonical.values());
+    const relations = [];
+    if (Array.isArray(item.relations)) {
+        for (const relation of item.relations) {
+            if (typeof relation !== "object" || relation === null || Array.isArray(relation))
+                continue;
+            const rel = relation;
+            const fromRaw = typeof rel.from === "string" ? normalizeEntityName(rel.from) : "";
+            const toRaw = typeof rel.to === "string" ? normalizeEntityName(rel.to) : "";
+            if (!fromRaw || !toRaw)
+                continue;
+            const from = entityCanonical.get(fromRaw.toLowerCase());
+            const to = entityCanonical.get(toRaw.toLowerCase());
+            if (!from || !to)
+                continue;
+            const type = typeof rel.type === "string" ? normalizeRelationType(rel.type) : undefined;
+            const confidence = parseConfidence(rel.confidence);
+            relations.push({
+                from,
+                to,
+                ...(type ? { type } : {}),
+                ...(confidence !== undefined ? { confidence } : {}),
+            });
+            if (relations.length >= MAX_RELATIONS_PER_ASSET)
+                break;
+        }
+    }
+    const confidence = parseConfidence(item.confidence);
+    return {
+        entities,
+        relations,
+        ...(confidence !== undefined ? { confidence } : {}),
+    };
+}
+/**
+ * Build the system prompt for a batched graph-extraction call.
+ *
+ * The prompt instructs the model to return a JSON array of exactly `count`
+ * objects, one per asset, in input order. Index alignment is the critical
+ * invariant — if the model drops an asset it still must emit an empty
+ * placeholder `{"entities":[],"relations":[]}` at that position.
+ *
+ * Worked example (3 assets, abbreviated):
+ *
+ *   Input user message:
+ *     Extract entities and relations from the N=3 assets below.
+ *     ...rules...
+ *     === ASSET 1 ===
+ *     ServiceA integrates with ServiceB.
+ *     === ASSET 2 ===
+ *     Terraform provisions the Prod cluster.
+ *     === ASSET 3 ===
+ *     No extractable graph content here.
+ *
+ *   Expected model output (valid JSON array, no prose):
+ *     [
+ *       {"entities":["ServiceA","ServiceB"],"relations":[{"from":"ServiceA","to":"ServiceB","type":"integrates with"}]},
+ *       {"entities":["Terraform","Prod cluster"],"relations":[{"from":"Terraform","to":"Prod cluster","type":"provisions"}]},
+ *       {"entities":[],"relations":[]}
+ *     ]
+ *
+ * If the model returns fewer than 3 items (partial failure), the caller
+ * (`extractGraphFromBodies`) falls back to individual calls for missing indices.
+ */
+function buildBatchSystemPrompt() {
+    return ("You extract knowledge graphs from developer notes. " +
+        "Return ONLY a valid JSON array — no prose, no markdown fences, no preamble. " +
+        "Each element of the array corresponds to one input asset, in order. " +
+        "The array length MUST equal the number of assets provided. " +
+        'Use {"entities":[],"relations":[]} for assets with no extractable graph content.');
+}
+function buildBatchUserPrompt(bodies) {
+    const count = bodies.length;
+    const assetBlocks = bodies
+        .map((body, i) => `${BATCH_ASSET_SEPARATOR} ${i + 1} ===\n${body.trim().slice(0, MAX_BODY_CHARS)}`)
+        .join("\n\n");
+    return (`Extract entities and relations from the N=${count} assets below.\n\n` +
+        `Rules:\n` +
+        `- Output ONLY a JSON array of exactly ${count} objects, one per asset, preserving input order.\n` +
+        `- Each object: {"entities": ["Entity One", ...], "relations": [{"from": "A", "to": "B", "type": "uses"}, ...]}\n` +
+        `- Entities are short, canonical noun phrases (project names, services, tools, people, file/dir names, technical concepts).\n` +
+        `- Relations connect two entities that both appear in that asset's entities array.\n` +
+        `- "type" is a short verb phrase (e.g. "uses", "depends on", "owns"). Optional; omit when unsure.\n` +
+        `- Drop pleasantries, meta-commentary, and timestamps.\n` +
+        `- Limit to at most ${MAX_ENTITIES_PER_ASSET} entities and ${MAX_RELATIONS_PER_ASSET} relations per asset.\n` +
+        `- Use {"entities":[],"relations":[]} for assets with no extractable graph content.\n` +
+        `- The array MUST have exactly ${count} elements — one placeholder per asset even if empty.\n\n` +
+        assetBlocks);
+}
+/**
+ * Parse and validate a single item from the batch response array.
+ * Mirrors the validation logic in `extractGraphFromBody`.
+ */
+function parseBatchItem(raw) {
+    return parseGraphExtraction(raw);
+}
+/**
+ * Extract entities and relations from multiple asset bodies in a single LLM
+ * call (batched graph extraction).
+ *
+ * Sends all `bodies` as a single prompt with `=== ASSET N ===` separators
+ * and expects a JSON array where element `i` corresponds to `bodies[i]`.
+ *
+ * **Partial-failure handling**: if the model returns fewer elements than
+ * `bodies.length`, missing indices are filled by falling back to individual
+ * `extractGraphFromBody` calls — ensuring every input always has a result.
+ *
+ * Returns an array of the same length as `bodies` (never shorter).
+ * Individual elements default to `{entities:[], relations:[]}` on failure.
+ *
+ * Routes through `tryLlmFeature("graph_extraction", ...)` so the feature gate
+ * and onFallback hook are honoured uniformly.
+ *
+ * @param llmConfig - LLM connection configuration.
+ * @param bodies    - Asset body strings to process in one batch.
+ * @param signal    - Optional AbortSignal for cancellation.
+ * @param akmConfig - Full AKM config (for feature-gate checks).
+ * @param onFallback - Optional fallback event sink.
+ */
+export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfig, onFallback) {
+    const empty = () => ({ entities: [], relations: [] });
+    // Degenerate case: no bodies → empty array (not an error).
+    if (bodies.length === 0)
+        return [];
+    // Single body: delegate to the single-asset path for identical behaviour.
+    if (bodies.length === 1) {
+        const result = await extractGraphFromBody(llmConfig, bodies[0] ?? "", signal, akmConfig, onFallback);
+        return [result];
+    }
+    // Filter out bodies that are empty so we don't waste tokens, but keep
+    // index correspondence by tracking which indices were non-empty.
+    const results = bodies.map(empty);
+    const nonEmptyIndices = [];
+    const nonEmptyBodies = [];
+    for (let i = 0; i < bodies.length; i++) {
+        const trimmed = (bodies[i] ?? "").trim();
+        if (trimmed) {
+            nonEmptyIndices.push(i);
+            nonEmptyBodies.push(trimmed);
+        }
+    }
+    if (nonEmptyBodies.length === 0)
+        return results;
+    const systemPrompt = buildBatchSystemPrompt();
+    const userPrompt = buildBatchUserPrompt(nonEmptyBodies);
+    const batchResult = await tryLlmFeature("graph_extraction", akmConfig, async () => {
+        try {
+            const raw = await chatCompletion(llmConfig, [
+                { role: "system", content: systemPrompt },
+                { role: "user", content: userPrompt },
+            ], {
+                temperature: 0.1,
+                timeoutMs: llmConfig.timeoutMs,
+                signal,
+            });
+            if (!raw)
+                return null;
+            const parsed = parseEmbeddedJsonResponse(raw);
+            if (!Array.isArray(parsed)) {
+                warn("graph extraction (batch): LLM response was not a JSON array; will fall back per-asset.");
+                return null;
+            }
+            return parsed;
+        }
+        catch (err) {
+            warn(`graph extraction (batch) failed: ${toErrorMessage(err)}`);
+            return null;
+        }
+    }, null, {
+        timeoutMs: llmConfig.timeoutMs,
+        onFallback,
+    });
+    // Map successful batch results back to their original indices.
+    if (batchResult !== null) {
+        for (let j = 0; j < nonEmptyBodies.length; j++) {
+            const originalIndex = nonEmptyIndices[j];
+            if (originalIndex === undefined)
+                continue;
+            if (j < batchResult.length) {
+                results[originalIndex] = parseBatchItem(batchResult[j]);
+            }
+            // j >= batchResult.length → partial failure; handled below.
+        }
+    }
+    // Partial-failure fallback: any non-empty body whose result is still the
+    // empty placeholder (either because batchResult was null or the array was
+    // shorter than expected) gets an individual retry.
+    const fallbackIndices = nonEmptyIndices.filter((_origIdx, j) => {
+        // Result is still empty → needs a fallback call.
+        if (batchResult === null)
+            return true;
+        // batchResult was shorter than the number of non-empty bodies.
+        return j >= batchResult.length;
+    });
+    if (fallbackIndices.length > 0) {
+        if (batchResult !== null) {
+            // Only warn on partial failure (not when the whole batch failed, which
+            // already emitted a warn above).
+            warn(`graph extraction (batch): response had ${batchResult.length} items for ${nonEmptyBodies.length} assets; ` +
+                `falling back to individual calls for ${fallbackIndices.length} missing asset(s).`);
+        }
+        await Promise.all(fallbackIndices.map(async (origIdx) => {
+            const body = bodies[origIdx] ?? "";
+            results[origIdx] = await extractGraphFromBody(llmConfig, body, signal, akmConfig, onFallback);
+        }));
+    }
+    return results;
+}
 /**
  * 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.
+ *
+ * Routes through `tryLlmFeature("graph_extraction", ...)` so the feature gate
+ * and onFallback hook are honoured uniformly (Fix C5).
  */
-export async function extractGraphFromBody(llmConfig, body, signal) {
+export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, onFallback) {
     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, [
+    return tryLlmFeature("graph_extraction", akmConfig, async () => {
+        try {
+            const raw = await chatCompletion(llmConfig, [
                 { role: "system", content: SYSTEM_PROMPT },
                 { role: "user", content: userPrompt },
-            ], { maxTokens: 1024, temperature: 0.1, timeoutMs: llmConfig.timeoutMs ?? 120_000, signal }),
-            new Promise((_, reject) => {
-                timeoutHandle = setTimeout(() => reject(new Error("graph extraction timed out")), llmConfig.timeoutMs ?? 120_000);
-            }),
-        ]);
-        if (!raw)
-            return empty;
-        const parsed = parseEmbeddedJsonResponse(raw);
-        if (!parsed) {
-            warn("graph extraction: invalid JSON response from LLM; skipping asset.");
+            ], { temperature: 0.1, timeoutMs: llmConfig.timeoutMs, signal });
+            if (!raw)
+                return empty;
+            const parsed = parseEmbeddedJsonResponse(raw);
+            if (!parsed) {
+                warn("graph extraction: invalid JSON response from LLM; skipping asset.");
+                return empty;
+            }
+            return parseGraphExtraction(parsed);
+        }
+        catch (err) {
+            warn(`graph extraction failed: ${toErrorMessage(err)}`);
             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);
-    }
+    }, empty, {
+        timeoutMs: llmConfig.timeoutMs,
+        onFallback,
+    });
 }
+// deduplicateGraph moved to src/indexer/graph-dedup.ts (pure utility, no LLM calls).
+export { deduplicateGraph } from "../indexer/graph-dedup";

package/dist/llm/memory-infer.js

@@ -18,32 +18,14 @@
 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;
 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":"string","description":"string","tags":["string"],"searchHints":["string"],"content":"string"}
+Rules: be specific, no vague generalizations, preserve key facts (names/versions/paths/config keys verbatim), merge related points, max 3 sentences body, 3-8 tags, 3-6 searchHints.
 
 Memory:
 `;
@@ -51,67 +33,63 @@ Memory:
  * 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: llmConfig.maxTokens ?? 4096,
                 temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs ?? 120_000,
+                timeoutMs: llmConfig.timeoutMs,
                 signal,
-            }),
-            new Promise((_, reject) => {
-                timeoutHandle = setTimeout(() => reject(new Error("memory inference timed out")), llmConfig.timeoutMs ?? 120_000);
-            }),
-        ]);
-        if (!raw)
-            return undefined;
-        const parsed = parseEmbeddedJsonResponse(raw);
-        if (!parsed) {
-            warn("memory inference: invalid JSON response from LLM; skipping memory.");
-            return undefined;
+            });
+            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

@@ -6,20 +6,27 @@
  * transport client in `client.ts`.
  */
 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 +37,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/graph-extract-user-prompt.md

@@ -0,0 +1,12 @@
+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.
+
+Asset body: