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

package/dist/llm/graph-extract.js

@@ -20,11 +20,13 @@
  * the connection via `resolveIndexPassLLM("graph", config)` and pass it
  * straight through.
  */
+import systemPromptTemplate from "../assets/prompts/graph-extract-system.md" with { type: "text" };
 import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
 import { toErrorMessage } from "../core/common.js";
 import { warn, warnVerbose } from "../core/warn.js";
-import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
+import { chatCompletion, isContextSizeError, parseEmbeddedJsonResponse } from "./client.js";
 import { tryLlmFeature } from "./feature-gate.js";
+import { callStructured } from "./structured-call.js";
 /**
  * Separator token used between assets in a batch prompt.
  * Chosen to be visually clear and unlikely to appear verbatim in asset bodies.
@@ -41,30 +43,15 @@ const NON_ARRAY_BATCH_DISABLE_THRESHOLD = 2;
 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, no preamble.";
+const SYSTEM_PROMPT = systemPromptTemplate;
 const USER_PROMPT_PREFIX = userPromptTemplate
     .replace("{{MAX_ENTITIES}}", String(MAX_ENTITIES_PER_ASSET))
     .replace("{{MAX_RELATIONS}}", String(MAX_RELATIONS_PER_ASSET));
-/**
- * Detect whether an error message indicates a context size exceeded condition.
- * Covers common patterns from OpenAI-compatible APIs (LM Studio, Ollama, etc).
- *
- * Requires BOTH a context keyword AND token-count/overflow evidence so that
- * model prose merely mentioning "context size" / "context length" (e.g. gemma
- * narrating about a document) does not get misclassified as a provider
- * context-limit error (#496).
- */
-export function isContextSizeError(message) {
-    const lower = message.toLowerCase();
-    const contextKw = /context (size|length|window)|prompt too long|exceeds.*context/.test(lower);
-    if (!contextKw) {
-        return false;
-    }
-    const evidence = /\b\d+\s*(token|tokens|tk)\b/.test(lower) ||
-        /max(imum)?\s+(context|token|input)/.test(lower) ||
-        /exceeded|over.*limit|too.*long/.test(lower);
-    return evidence;
-}
+// `isContextSizeError` is defined in `./client` and re-exported here so the
+// graph extractor and the retry classifier (`isRetryable`) share one
+// definition (#496). Re-exported (not just imported) to preserve existing
+// importers of this module — including its unit test.
+export { isContextSizeError } from "./client.js";
 const GENERIC_ENTITIES = new Set([
     "agent",
     "application",
@@ -327,7 +314,13 @@ function parseGraphExtraction(raw) {
             if (!normalized)
                 continue;
             const normalizedKey = normalized.toLowerCase();
-            if (!/[a-z0-9]/i.test(normalized) || GENERIC_ENTITIES.has(normalizedKey)) {
+            // Drop generic/empty entities AND raw file/dir paths (anything with a
+            // path separator) — the prompt no longer asks for them and isJunkEntity
+            // discards them downstream, so emitting them is pure waste/junk (#632).
+            if (!/[a-z0-9]/i.test(normalized) ||
+                GENERIC_ENTITIES.has(normalizedKey) ||
+                normalized.includes("/") ||
+                normalized.includes("\\")) {
                 filteredGenericEntities += 1;
                 continue;
             }
@@ -432,6 +425,18 @@ function buildBatchSystemPrompt() {
         "The array length MUST equal the number of assets provided. " +
         'Use {"entities":[],"relations":[]} for assets with no extractable graph content.');
 }
+/**
+ * Hardened system prompt for the single batch retry (#635). Used only after a
+ * first response failed array salvage — leans harder on "raw array only" so a
+ * model that wrapped the array in prose/fences corrects itself before we pay
+ * the per-asset fallback.
+ */
+function buildBatchRetrySystemPrompt() {
+    return (`${buildBatchSystemPrompt()} ` +
+        "Your previous response could NOT be parsed as a JSON array. " +
+        "Respond with ONLY the raw JSON array — start with '[' and end with ']'. " +
+        "No prose, no explanation, no markdown code fences, no preamble.");
+}
 function buildBatchUserPrompt(bodies) {
     const count = bodies.length;
     const assetBlocks = bodies.map((body, i) => `${BATCH_ASSET_SEPARATOR} ${i + 1} ===\n${body.trim()}`).join("\n\n");
@@ -541,7 +546,21 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
             });
             if (!raw)
                 return null;
-            const parsed = parseEmbeddedJsonResponse(raw);
+            // Array-preferring salvage (#635): the batch contract is a top-level
+            // JSON array. A leading/example `{…}` object in the response must not
+            // mask a valid `[…]` array as a false "non-array" failure.
+            let parsed = parseEmbeddedJsonResponse(raw, { expect: "array" });
+            if (!Array.isArray(parsed)) {
+                // One stricter-reprompt retry before paying the per-asset fallback
+                // (#635). Many genuine non-array responses recover when the model is
+                // told explicitly to emit only the raw array.
+                bumpTelemetry(options.telemetry, "retryAttempts");
+                const retryRaw = await chatCompletion(llmConfig, [
+                    { role: "system", content: buildBatchRetrySystemPrompt() },
+                    { role: "user", content: userPrompt },
+                ], { temperature: 0, timeoutMs: llmConfig.timeoutMs, signal });
+                parsed = retryRaw ? parseEmbeddedJsonResponse(retryRaw, { expect: "array" }) : undefined;
+            }
             if (!Array.isArray(parsed)) {
                 nonArrayResponse = true;
                 bumpTelemetry(options.telemetry, "nonArrayBatchFailures");
@@ -551,8 +570,9 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
                         batchState.batchingDisabled = true;
                     }
                 }
-                warn(`graph extraction (batch): LLM response was not a JSON array for ${nonEmptyBodies.length} asset(s); ` +
-                    `will fall back per-asset. promptChars=${userPrompt.length}${formatContextHint(llmConfig)}`);
+                warn(`graph extraction (batch): LLM response was not a JSON array for ${nonEmptyBodies.length} asset(s) ` +
+                    `even after a stricter retry; will fall back per-asset. ` +
+                    `promptChars=${userPrompt.length}${formatContextHint(llmConfig)}`);
                 return null;
             }
             return parsed;
@@ -675,17 +695,21 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
         return merged;
     }
     const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody}`;
-    return tryLlmFeature("graph_extraction", akmConfig, async () => {
-        try {
-            const raw = await chatCompletion(llmConfig, [
-                { role: "system", content: SYSTEM_PROMPT },
-                { role: "user", content: userPrompt },
-            ], {
-                temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs,
-                signal,
-                onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
-            });
+    return callStructured({
+        feature: "graph_extraction",
+        akmConfig,
+        config: llmConfig,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ],
+        request: {
+            temperature: 0.1,
+            timeoutMs: llmConfig.timeoutMs,
+            signal,
+            onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
+        },
+        parse: (raw) => {
             if (!raw)
                 return empty();
             const parsed = parseEmbeddedJsonResponse(raw);
@@ -701,16 +725,16 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
             if (extraction.status === "failed")
                 bumpTelemetry(options.telemetry, "failureCount");
             return extraction;
-        }
-        catch (err) {
+        },
+        onError: (cls, err) => {
             const errMsg = toErrorMessage(err);
-            if (isContextSizeError(errMsg)) {
+            if (cls === "context_limit") {
                 bumpTelemetry(options.telemetry, "failureCount");
                 warn(`graph extraction: context size exceeded for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}. ` +
                     `Consider increasing llm.contextLength in config.json.`);
                 return empty("context_limit", "failed");
             }
-            else if (err instanceof LlmCallError && err.code === "provider_html_error") {
+            else if (cls === "html") {
                 bumpTelemetry(options.telemetry, "htmlErrorCount");
                 warn(`graph extraction: provider returned HTML instead of JSON for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}: ${errMsg}`);
                 return empty("llm_error", "failed");
@@ -720,9 +744,8 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
                 warn(`graph extraction failed for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}: ${errMsg}`);
                 return empty("llm_error", "failed");
             }
-        }
-    }, empty(), {
-        timeoutMs: llmConfig.timeoutMs,
+        },
+        fallback: empty(),
         onFallback,
     });
 }

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

@@ -0,0 +1,138 @@
+// 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).
+ *
+ * Compresses a single memory body into one higher-signal derived memory. The
+ * pass itself (in `src/indexer/memory-inference.ts`) is responsible for
+ * deciding which memories are pending, persisting the derived memory with the
+ * correct frontmatter (`inferred: true`, `source: <parent-ref>`), and marking
+ * the parent as processed for idempotency.
+ *
+ * This module is intentionally tiny and stateless so tests can stub it via
+ * `mock.module("../src/llm/memory-infer", ...)` without hitting a network.
+ *
+ * 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 memoryInferSystemPrompt from "../assets/prompts/memory-infer-system.md" with { type: "text" };
+import memoryInferUserPrompt from "../assets/prompts/memory-infer-user.md" with { type: "text" };
+import { toErrorMessage } from "../core/common.js";
+import { warn } from "../core/warn.js";
+import { parseEmbeddedJsonResponse } from "./client.js";
+import { callStructured } from "./structured-call.js";
+/** Hard cap on body chars sent to the model — pragmatic and matches `runLlmEnrich`. */
+const MAX_BODY_CHARS = 4000;
+const SYSTEM_PROMPT = memoryInferSystemPrompt;
+const USER_PROMPT_PREFIX = memoryInferUserPrompt;
+/**
+ * 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
+ * must not abort the rest of the index pass.
+ *
+ * Routes through `callStructured({ feature: "memory_inference", ... })` so the
+ * feature gate, error classification, and onFallback hook are honoured uniformly
+ * (Fix C5).
+ */
+export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt) {
+    const trimmedBody = body.trim();
+    if (!trimmedBody)
+        return undefined;
+    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
+    // Memory-inference is ALWAYS gated: no `akmConfig` ⇒ gate closed (no chat,
+    // `disabled` fallback), never the seam's ungated/propagate path (which is for
+    // direct callers like `enhanceMetadata`). This is the gate-closed branch
+    // `tryLlmFeature(_, undefined, _)` took before the migration.
+    if (!akmConfig) {
+        onFallback?.({ feature: "memory_inference", reason: "disabled" });
+        return undefined;
+    }
+    return callStructured({
+        feature: "memory_inference",
+        akmConfig,
+        config: llmConfig,
+        messages: [
+            { role: "system", content: SYSTEM_PROMPT },
+            { role: "user", content: userPrompt },
+        ],
+        request: {
+            temperature: 0.1,
+            timeoutMs: llmConfig.timeoutMs,
+            signal,
+            responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
+            onRetryAttempt,
+        },
+        parse: (raw) => {
+            if (!raw)
+                return undefined;
+            const parsed = parseEmbeddedJsonResponse(raw);
+            if (!parsed) {
+                warn("memory inference: invalid JSON response from LLM; skipping memory.");
+                return undefined;
+            }
+            const title = typeof parsed.title === "string" ? parsed.title.trim() : "";
+            const description = typeof parsed.description === "string" ? parsed.description.trim() : "";
+            const content = typeof parsed.content === "string" ? parsed.content.trim() : "";
+            const tags = Array.isArray(parsed.tags)
+                ? parsed.tags
+                    .filter((t) => typeof t === "string")
+                    .map((t) => t.trim())
+                    .filter(Boolean)
+                    .slice(0, 8)
+                : [];
+            const searchHints = Array.isArray(parsed.searchHints)
+                ? parsed.searchHints
+                    .filter((h) => typeof h === "string")
+                    .map((h) => h.trim())
+                    .filter(Boolean)
+                    .slice(0, 6)
+                : [];
+            if (!title || !description || !content || tags.length === 0 || searchHints.length === 0) {
+                warn("memory inference: incomplete derived memory payload from LLM; skipping memory.");
+                return undefined;
+            }
+            return { title, description, tags, searchHints, content };
+        },
+        onError: (cls, err) => {
+            if (cls === "html") {
+                if (telemetry)
+                    telemetry.htmlErrorCount = (telemetry.htmlErrorCount ?? 0) + 1;
+                warn(`memory inference: provider returned HTML instead of JSON; skipping memory: ${toErrorMessage(err)}`);
+                return undefined;
+            }
+            warn(`memory inference failed: ${toErrorMessage(err)}`);
+            return undefined;
+        },
+        fallback: undefined,
+        onFallback,
+    });
+}

package/dist/llm/memory-infer.js

@@ -1,130 +1,4 @@
 // 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).
- *
- * Compresses a single memory body into one higher-signal derived memory. The
- * pass itself (in `src/indexer/memory-inference.ts`) is responsible for
- * deciding which memories are pending, persisting the derived memory with the
- * correct frontmatter (`inferred: true`, `source: <parent-ref>`), and marking
- * the parent as processed for idempotency.
- *
- * This module is intentionally tiny and stateless so tests can stub it via
- * `mock.module("../src/llm/memory-infer", ...)` without hitting a network.
- *
- * 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.js";
-import { warn } from "../core/warn.js";
-import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
-import { tryLlmFeature } from "./feature-gate.js";
-/** 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 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
- * 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, akmConfig, onFallback, telemetry, onRetryAttempt) {
-    const trimmedBody = body.trim();
-    if (!trimmedBody)
-        return undefined;
-    const userPrompt = `${USER_PROMPT_PREFIX}${trimmedBody.slice(0, MAX_BODY_CHARS)}`;
-    return tryLlmFeature("memory_inference", akmConfig, async () => {
-        try {
-            const raw = await chatCompletion(llmConfig, [
-                { role: "system", content: SYSTEM_PROMPT },
-                { role: "user", content: userPrompt },
-            ], {
-                temperature: 0.1,
-                timeoutMs: llmConfig.timeoutMs,
-                signal,
-                responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
-                onRetryAttempt,
-            });
-            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 };
-        }
-        catch (err) {
-            if (err instanceof LlmCallError && err.code === "provider_html_error") {
-                if (telemetry)
-                    telemetry.htmlErrorCount = (telemetry.htmlErrorCount ?? 0) + 1;
-                warn(`memory inference: provider returned HTML instead of JSON; skipping memory: ${toErrorMessage(err)}`);
-                return undefined;
-            }
-            warn(`memory inference failed: ${toErrorMessage(err)}`);
-            return undefined;
-        }
-    }, undefined, {
-        timeoutMs: llmConfig.timeoutMs,
-        onFallback,
-    });
-}
+export { compressMemoryToDerivedMemory, } from "./memory-infer-impl.js";

package/dist/llm/metadata-enhance.js

@@ -1,9 +1,17 @@
 // 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.js";
-import { tryLlmFeature } from "./feature-gate.js";
-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.`;
+/**
+ * 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`.
+ */
+import metadataEnhanceSystemPrompt from "../assets/prompts/metadata-enhance-system.md" with { type: "text" };
+import { parseJsonResponse } from "./client.js";
+import { callStructured } from "./structured-call.js";
+const SYSTEM_PROMPT = metadataEnhanceSystemPrompt;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,
  * generate searchHints, and suggest tags.
@@ -33,34 +41,39 @@ 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 runLlm = async () => {
-        const raw = await chatCompletion(config, [
+    // `parse` owns the raw response: the `!raw`/unparseable case ⇒ `{}`, plus the
+    // description/searchHints/tags shaping. `enhanceMetadata` never warns and
+    // never bumps telemetry, so `onError` (gated path only) just swallows to `{}`
+    // — identical to the surrounding control flow's pre-migration behaviour. The
+    // ungated path (akmConfig === undefined) propagates errors via callStructured.
+    return callStructured({
+        feature: "metadata_enhance",
+        akmConfig,
+        config,
+        messages: [
             { 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 tryLlmFeature("metadata_enhance", akmConfig, runLlm, {}, { timeoutMs: config.timeoutMs });
+        ],
+        request: { signal, timeoutMs: config.timeoutMs },
+        parse: (raw) => {
+            const parsed = raw ? parseJsonResponse(raw) : undefined;
+            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;
+        },
+        onError: () => ({}),
+        fallback: {},
+    });
 }

package/dist/llm/structured-call.js

@@ -0,0 +1,49 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { chatCompletion, isContextSizeError, LlmCallError } from "./client.js";
+import { tryLlmFeature } from "./feature-gate.js";
+/**
+ * Classify a thrown LLM error into one of the three buckets. This is the single
+ * home for the `isContextSizeError -> html -> other` ladder that was previously
+ * inlined at every call site.
+ */
+export function classifyLlmError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (isContextSizeError(message))
+        return "context_limit";
+    if (err instanceof LlmCallError && err.code === "provider_html_error")
+        return "html";
+    return "other";
+}
+export async function callStructured(opts) {
+    const { feature, akmConfig, config, messages, request, parse, onError, fallback, onFallback } = opts;
+    const chat = request?.chat ?? chatCompletion;
+    const chatOptions = {
+        temperature: request?.temperature,
+        timeoutMs: request?.timeoutMs,
+        signal: request?.signal,
+        responseSchema: request?.responseSchema,
+        onRetryAttempt: request?.onRetryAttempt,
+    };
+    // UNGATED: run the chat+parse directly. Errors propagate — no `onError`
+    // funnel — matching the pre-gate behaviour of direct callers.
+    if (akmConfig === undefined) {
+        const raw = await chat(config, messages, chatOptions);
+        return parse(raw);
+    }
+    // GATED: run through `tryLlmFeature`. A throw inside is classified ONCE and
+    // routed to `onError`; `tryLlmFeature` returns `fallback` on disablement/timeout.
+    return tryLlmFeature(feature, akmConfig, async () => {
+        try {
+            const raw = await chat(config, messages, chatOptions);
+            return parse(raw);
+        }
+        catch (err) {
+            return onError(classifyLlmError(err), err);
+        }
+    }, fallback, {
+        timeoutMs: request?.timeoutMs,
+        onFallback,
+    });
+}

package/dist/migrate-storage-node.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// 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/.
+
+const { main } = await import("./scripts/migrate-storage.js");
+
+await main();

package/dist/output/context.js

@@ -12,10 +12,10 @@
  * Initialized from `cli.ts` before `runMain`.
  */
 import { UsageError } from "../core/errors.js";
-export const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md", "html"];
-export const DETAIL_LEVELS = ["brief", "normal", "full"];
-export const SHAPE_MODES = ["human", "agent", "summary"];
-export function parseOutputFormat(value) {
+const OUTPUT_FORMATS = ["json", "yaml", "text", "jsonl", "md", "html"];
+const DETAIL_LEVELS = ["brief", "normal", "full"];
+const SHAPE_MODES = ["human", "agent", "summary"];
+function parseOutputFormat(value) {
     if (!value)
         return undefined;
     if (OUTPUT_FORMATS.includes(value))
@@ -29,7 +29,7 @@ export function parseDetailLevel(value) {
         return value;
     throw new UsageError(`Invalid value for --detail: ${value}. Expected one of: ${DETAIL_LEVELS.join("|")}`, "INVALID_DETAIL_VALUE");
 }
-export function parseShapeMode(value) {
+function parseShapeMode(value) {
     if (!value)
         return undefined;
     if (SHAPE_MODES.includes(value))