akm-cli 0.8.7 → 0.8.14

package/dist/integrations/lockfile.js

@@ -3,24 +3,15 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import fs from "node:fs";
 import path from "node:path";
-import { writeFileAtomic } from "../core/common";
-import { rethrowIfTestIsolationError } from "../core/errors";
-import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock";
-import { getDataDir } from "../core/paths";
-// ── Paths ───────────────────────────────────────────────────────────────────
-const LOCKFILE_NAME = "akm.lock";
-function getLockfilePath() {
-    return path.join(getDataDir(), LOCKFILE_NAME);
-}
+import { writeFileAtomic } from "../core/common.js";
+import { rethrowIfTestIsolationError } from "../core/errors.js";
+import { probeLock, releaseLock, tryAcquireLockSync } from "../core/file-lock.js";
+import { getDataDir, getLockfileLockPath, getLockfilePath } from "../core/paths.js";
 // ── Lock sentinel ────────────────────────────────────────────────────────────
 const LOCK_MAX_RETRIES = 3;
 const LOCK_RETRY_DELAY_MS = 100;
-function getLockSentinelPath() {
-    // The sentinel always lives next to the lock file it guards.
-    return `${path.join(getDataDir(), LOCKFILE_NAME)}.lck`;
-}
 async function acquireLockSentinel() {
-    const sentinelPath = getLockSentinelPath();
+    const sentinelPath = getLockfileLockPath();
     // Ensure the directory exists before attempting to create the sentinel.
     fs.mkdirSync(path.dirname(sentinelPath), { recursive: true });
     for (let attempt = 0; attempt < LOCK_MAX_RETRIES; attempt++) {
@@ -40,7 +31,7 @@ async function acquireLockSentinel() {
     return false;
 }
 function releaseLockSentinel() {
-    releaseLock(getLockSentinelPath());
+    releaseLock(getLockfileLockPath());
 }
 // ── Read / Write ────────────────────────────────────────────────────────────
 export function readLockfile() {
@@ -61,7 +52,7 @@ export function readLockfile() {
 }
 export function writeLockfile(entries) {
     // Always write to $DATA — never to the legacy $CONFIG location.
-    const lockfilePath = path.join(getDataDir(), LOCKFILE_NAME);
+    const lockfilePath = getLockfilePath();
     const dir = path.dirname(lockfilePath);
     fs.mkdirSync(dir, { recursive: true });
     writeFileAtomic(lockfilePath, `${JSON.stringify(entries, null, 2)}\n`);

package/dist/integrations/session-logs/index.js

@@ -1,10 +1,25 @@
 // 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 { ClaudeCodeProvider } from "./providers/claude-code";
-import { OpenCodeProvider } from "./providers/opencode";
-export { extractInlineRefMentions } from "./inline-refs";
+import { getHarness, SESSION_LOG_HARNESSES } from "../harnesses/index.js";
+import { ClaudeCodeProvider } from "../harnesses/claude/session-log.js";
+import { OpenCodeProvider } from "../harnesses/opencode/session-log.js";
+export { extractInlineRefMentions } from "./inline-refs.js";
 const HARNESSES = [new ClaudeCodeProvider(), new OpenCodeProvider()];
+// #562: the unified HARNESS_REGISTRY is the single source of truth for which
+// harnesses expose session logs. Validate (behaviour-preserving) that every
+// session-log provider instantiated above resolves to a registry harness whose
+// `sessionLogs` capability is set — and via the id-normalization bridge, so a
+// provider named "claude-code" still maps to the canonical "claude" harness.
+// This turns a silently-drifting third registry into a startup invariant.
+for (const provider of HARNESSES) {
+    const harness = getHarness(provider.name);
+    if (!harness?.capabilities.sessionLogs) {
+        throw new Error(`[akm] session-log provider "${provider.name}" is not registered as a sessionLogs harness in HARNESS_REGISTRY (src/integrations/harnesses). Add it there.`);
+    }
+}
+// Touch the derived list so the dependency is explicit and tree-shake-safe.
+void SESSION_LOG_HARNESSES;
 const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENOENT|timeout/i;
 /**
  * Returns all available session log harnesses for the current machine.
@@ -51,19 +66,77 @@ export function aggregateSessionEvents(events) {
     }));
 }
 /**
- * Scan recent session logs from all available harnesses and return
- * repeated failure patterns that might warrant new AKM assets.
+ * Collect normalized session events from a set of harnesses for the health
+ * candidate scan (#568).
+ *
+ * Pipeline selection per harness (capability-gated):
+ *   - readSession-capable harness (`supportsReadSession !== false`): drive the
+ *     richer `listSessions()` + `readSession()` pipeline. `readSession` flattens
+ *     structured content — tool calls, assistant content blocks, thinking,
+ *     tool_result — into event text (e.g. ClaudeCodeProvider's `parseClaudeEvent`
+ *     surfaces `[tool:*]` / `[tool_result]` blocks that the legacy flat
+ *     `readEvents` scan drops entirely). This is what lets health advisories see
+ *     repeated tool failures / long runs that the flat scan hid.
+ *   - legacy-only harness (`supportsReadSession === false`): fall back to the
+ *     legacy flat `readEvents()` scan (behaviour-preserving).
+ *
+ * Extracted as a pure function (harnesses injected) so it is unit-testable
+ * without touching the real on-disk session-log locations.
+ *
+ * `maxSessionsPerHarness` bounds the rich path: `readSession()` reads each
+ * session file IN FULL (unlike the legacy flat scan, which only touched files
+ * with mtime ≥ sinceMs and skipped non-string content). On a machine with a
+ * deep `~/.claude/projects` history a 30-day window can hold hundreds of
+ * multi-MB session files, and reading+parsing every one in full made the
+ * health command (`akm health`, which calls this synchronously) blow past its
+ * latency budget. `listSessions()` returns summaries sorted newest-first, so
+ * capping to the most-recent N sessions per harness keeps the richer signal
+ * for what actually matters (recent activity) while bounding cost. The legacy
+ * flat-scan path is naturally cheaper and is left uncapped.
  */
-export function getExecutionLogCandidates(sinceDays = 7) {
-    const sinceMs = Date.now() - sinceDays * 24 * 60 * 60 * 1000;
+const DEFAULT_MAX_SESSIONS_PER_HARNESS = 50;
+export function collectSessionEvents(harnesses, sinceMs, maxSessionsPerHarness = DEFAULT_MAX_SESSIONS_PER_HARNESS) {
     const events = [];
-    for (const harness of getAvailableHarnesses()) {
+    for (const harness of harnesses) {
         try {
-            events.push(...harness.readEvents({ sinceMs }));
+            if (harness.supportsReadSession === false) {
+                // Legacy-only harness: only the flat event scan is available.
+                events.push(...harness.readEvents({ sinceMs }));
+                continue;
+            }
+            // Rich path: enumerate sessions cheaply, then read each one's full
+            // structured event stream. Falls back to readEvents if listSessions
+            // surfaces nothing (e.g. a harness that wired readSession but whose
+            // listSessions returns empty on this machine) so we never regress
+            // coverage relative to the legacy scan.
+            const summaries = harness.listSessions({ sinceMs });
+            if (summaries.length === 0) {
+                events.push(...harness.readEvents({ sinceMs }));
+                continue;
+            }
+            // summaries are newest-first; bound the full-file reads (see doc above).
+            for (const summary of summaries.slice(0, maxSessionsPerHarness)) {
+                try {
+                    const session = harness.readSession(summary);
+                    events.push(...session.events);
+                }
+                catch {
+                    // a single unreadable session is non-fatal
+                }
+            }
         }
         catch {
             // individual harness failures are non-fatal
         }
     }
+    return events;
+}
+/**
+ * Scan recent session logs from all available harnesses and return
+ * repeated failure patterns that might warrant new AKM assets.
+ */
+export function getExecutionLogCandidates(sinceDays = 7) {
+    const sinceMs = Date.now() - sinceDays * 24 * 60 * 60 * 1000;
+    const events = collectSessionEvents(getAvailableHarnesses(), sinceMs);
     return aggregateSessionEvents(events);
 }

package/dist/llm/call-ai.js

@@ -1,10 +1,10 @@
 // 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 } from "../core/config";
-import { warn } from "../core/warn";
-import { resolveAgentProfile, runAgent } from "../integrations/agent";
-import { chatCompletion } from "./client";
+import { getDefaultLlmConfig } from "../core/config/config.js";
+import { warn } from "../core/warn.js";
+import { resolveAgentProfile, runAgent } from "../integrations/agent/index.js";
+import { chatCompletion } from "./client.js";
 /**
  * Unified AI call: prefers the default agent profile, falls back to the
  * default LLM profile. When neither is configured, returns a structured

package/dist/llm/client.js

@@ -10,12 +10,14 @@
  *
  * `llm.ts` re-exports everything from this module for backward compatibility.
  */
-import { fetchWithTimeout } from "../core/common";
-import { resolveSecret } from "../core/config";
-import { escapeJsonStringControls, parseJsonResponse, stripCodeFences, stripThinkBlocks } from "../core/parse";
+import { fetchWithTimeout } from "../core/common.js";
+import { resolveSecret } from "../core/config/config.js";
+import { escapeJsonStringControls, parseJsonResponse, stripCodeFences, stripThinkBlocks } from "../core/parse.js";
+import { warnVerbose } from "../core/warn.js";
+import { emitLlmUsage, extractUsageTokens } from "./usage-telemetry.js";
 // Re-export shared parse utilities so existing importers of `client.ts` continue
 // to resolve `parseJsonResponse` and `parseEmbeddedJsonResponse` from this module.
-export { escapeJsonStringControls, parseEmbeddedJsonResponse, parseJsonResponse, stripCodeFences, stripThinkBlocks, } from "../core/parse";
+export { escapeJsonStringControls, parseEmbeddedJsonResponse, parseJsonResponse, stripCodeFences, stripThinkBlocks, } from "../core/parse.js";
 /** Maximum length of an LLM error response body included in thrown errors. */
 const ERROR_BODY_MAX_LEN = 200;
 /**
@@ -46,6 +48,27 @@ export function redactErrorBody(input) {
     }
     return out;
 }
+/**
+ * Detect a response body that is an HTML document rather than the expected
+ * JSON. LM Studio (and similar local providers) can serve their web UI on
+ * partial-load / startup failures, producing an HTML page where the OpenAI
+ * API contract promises JSON.
+ */
+function isHtmlResponse(body) {
+    const lower = body.trimStart().toLowerCase();
+    return lower.startsWith("<!doctype html") || lower.startsWith("<html");
+}
+/**
+ * Produce a short plain-text excerpt of an HTML body for inclusion in error
+ * messages: strip tags, collapse whitespace, and truncate.
+ */
+function htmlExcerpt(body) {
+    const text = body
+        .replace(/<[^>]*>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    return text.length > ERROR_BODY_MAX_LEN ? `${text.slice(0, ERROR_BODY_MAX_LEN)}…` : text;
+}
 export class LlmCallError extends Error {
     code;
     statusCode;
@@ -56,8 +79,95 @@ export class LlmCallError extends Error {
         this.name = "LlmCallError";
     }
 }
+// ── Single bounded retry for transient failures ─────────────────────────────
+/** Lower bound of the jittered retry backoff (inclusive), in milliseconds. */
+const RETRY_BACKOFF_MIN_MS = 200;
+/** Upper bound of the jittered retry backoff (exclusive-ish), in milliseconds. */
+const RETRY_BACKOFF_MAX_MS = 800;
+/**
+ * Fraction of the effective timeout budget that, once consumed by the first
+ * attempt, causes the retry to be skipped — there is not enough budget left
+ * for a meaningful second attempt.
+ */
+const RETRY_BUDGET_FRACTION = 0.9;
+/**
+ * Sleep for `ms` milliseconds. Extracted as a named helper so tests can stub
+ * the backoff via the internal `sleep` option on {@link chatCompletion} and
+ * avoid real delays.
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Compute a uniform jittered backoff in the [200, 800)ms range. */
+function retryBackoffMs() {
+    return RETRY_BACKOFF_MIN_MS + Math.random() * (RETRY_BACKOFF_MAX_MS - RETRY_BACKOFF_MIN_MS);
+}
+/**
+ * Detect whether an error message indicates a context-size-exceeded condition.
+ * Mirrors the heuristic in `graph-extract.ts` — retrying a context overflow
+ * cannot shrink the input, so it must not be retried.
+ */
+function looksLikeContextOverflow(message) {
+    const lower = message.toLowerCase();
+    return (lower.includes("context") &&
+        (lower.includes("context size") ||
+            lower.includes("context length") ||
+            lower.includes("context_window") ||
+            lower.includes("prompt too long") ||
+            lower.includes("exceeds")));
+}
+/**
+ * Decide whether a first-attempt {@link LlmCallError} is eligible for a single
+ * retry. Retryable: HTTP 5xx (`provider_error` with statusCode >= 500) and
+ * `network_error` whose message looks like a transient connection reset
+ * (ECONNRESET / EPIPE / "fetch failed"). NOT retryable: 4xx, `rate_limited`
+ * (429), `timeout`, `parse_error`, and context-overflow-classified errors.
+ */
+function isRetryable(err) {
+    if (looksLikeContextOverflow(err.message))
+        return false;
+    if (err.code === "provider_error") {
+        return typeof err.statusCode === "number" && err.statusCode >= 500;
+    }
+    if (err.code === "network_error") {
+        const lower = err.message.toLowerCase();
+        return lower.includes("econnreset") || lower.includes("epipe") || lower.includes("fetch failed");
+    }
+    return false;
+}
 export async function chatCompletion(config, messages, options) {
-    const timeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 120_000;
+    const effectiveTimeoutMs = options?.timeoutMs ?? config.timeoutMs ?? 120_000;
+    const started = Date.now();
+    try {
+        return await chatCompletionAttempt(config, messages, options, effectiveTimeoutMs);
+    }
+    catch (err) {
+        if (!(err instanceof LlmCallError) || !isRetryable(err))
+            throw err;
+        // Timeout-budget guard: if the first attempt already burned most of the
+        // budget, a second attempt cannot complete — skip the retry.
+        const elapsed = Date.now() - started;
+        const remaining = effectiveTimeoutMs - elapsed;
+        if (elapsed >= effectiveTimeoutMs * RETRY_BUDGET_FRACTION || remaining <= 0) {
+            throw err;
+        }
+        // Signal the caller so it can bump `retryAttempts` (NOT `failureCount`).
+        options?.onRetryAttempt?.();
+        // Log the first failure at debug (verbose-only) level; the retry outcome is
+        // authoritative.
+        warnVerbose(`[akm] LLM transient failure (${err.code}); retrying once: ${err.message}`);
+        const wait = retryBackoffMs();
+        await (options?.sleep ?? sleep)(wait);
+        // The retry must not exceed the original budget.
+        return await chatCompletionAttempt(config, messages, options, remaining);
+    }
+}
+/**
+ * A single chat-completion attempt: one HTTP request/response cycle with no
+ * retry. {@link chatCompletion} wraps this with a single bounded retry for
+ * transient failures.
+ */
+async function chatCompletionAttempt(config, messages, options, timeoutMs) {
     const headers = { "Content-Type": "application/json" };
     const resolvedKey = resolveSecret(config.apiKey);
     if (resolvedKey) {
@@ -70,6 +180,10 @@ export async function chatCompletion(config, messages, options) {
     const responseFormat = options?.responseSchema && config.supportsJsonSchema
         ? { response_format: { type: "json_schema", json_schema: { schema: options.responseSchema, strict: true } } }
         : {};
+    // Wall-clock start for per-call usage telemetry (#576). Captured here so the
+    // emitted duration covers the full request/response/parse cycle of a single
+    // attempt, not the retry-wrapping `chatCompletion`.
+    const requestStartedAt = Date.now();
     let response;
     try {
         response = await fetchWithTimeout(config.endpoint, {
@@ -110,12 +224,38 @@ export async function chatCompletion(config, messages, options) {
         if (status === 429) {
             throw new LlmCallError(`LLM request rate limited (429) ${config.endpoint}: ${safeBody}`, "rate_limited", status);
         }
+        if (status >= 500 && isHtmlResponse(rawBody)) {
+            throw new LlmCallError(`LLM provider returned HTML instead of JSON (${status}) ${config.endpoint}: ${htmlExcerpt(rawBody)}`, "provider_html_error", status);
+        }
         if (status >= 500) {
             throw new LlmCallError(`LLM provider error (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
         }
         throw new LlmCallError(`LLM request failed (${status}) ${config.endpoint}: ${safeBody}`, "provider_error", status);
     }
-    const json = (await response.json());
+    // A 2xx response is still an error if the body is HTML where JSON was
+    // expected (e.g. a provider serving its web UI). Read the raw body first so
+    // we can categorize an HTML page distinctly from a malformed-JSON parse_error.
+    const rawOkBody = await response.text();
+    if (isHtmlResponse(rawOkBody)) {
+        throw new LlmCallError(`LLM provider returned HTML instead of JSON (${response.status}) ${config.endpoint}: ${htmlExcerpt(rawOkBody)}`, "provider_html_error", response.status);
+    }
+    let json;
+    try {
+        json = JSON.parse(rawOkBody);
+    }
+    catch {
+        throw new LlmCallError(`LLM response was not valid JSON ${config.endpoint}: ${redactErrorBody(rawOkBody)}`, "parse_error", response.status);
+    }
+    // Per-call usage telemetry (#576). Best-effort and fully isolated: a missing
+    // or garbled usage block still records duration + model, and a throwing sink
+    // can never fail the call (emitLlmUsage swallows its own errors). The stage
+    // is supplied ambiently by emitLlmUsage; no `stage` param is threaded here.
+    emitLlmUsage({
+        model: typeof json.model === "string" && json.model ? json.model : config.model,
+        durationMs: Date.now() - requestStartedAt,
+        finishReason: typeof json.choices?.[0]?.finish_reason === "string" ? json.choices[0].finish_reason : undefined,
+        ...extractUsageTokens(json.usage),
+    });
     const content = (json.choices?.[0]?.message?.content ?? "").trim();
     const reasoning = (json.choices?.[0]?.message?.reasoning_content ?? "").trim();
     return content || reasoning;

package/dist/llm/embedder.js

@@ -1,12 +1,12 @@
 // 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 { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache";
-import { isTransformersAvailable, LocalEmbedder } from "./embedders/local";
-import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote";
+import { embedCacheKey, getCachedEmbedding, setCachedEmbedding } from "./embedders/cache.js";
+import { isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
+import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
-export { clearEmbeddingCache } from "./embedders/cache";
-export { DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedders/local";
+export { clearEmbeddingCache } from "./embedders/cache.js";
+export { DEFAULT_LOCAL_MODEL, isTransformersAvailable } from "./embedders/local.js";
 // ── Singleton local embedder ────────────────────────────────────────────────
 // `_localEmbedder` is an intentional module-level singleton but constructed
 // lazily on first use. The underlying @huggingface/transformers pipeline is
@@ -76,7 +76,7 @@ export async function embedBatch(texts, embeddingConfig, signal) {
 // (notably `db.ts`) can pull the math function without dragging in this
 // facade and its `@huggingface/transformers` import chain. Re-export
 // preserves the existing public API.
-export { cosineSimilarity } from "./embedders/types";
+export { cosineSimilarity } from "./embedders/types.js";
 // ── Availability check ──────────────────────────────────────────────────────
 /**
  * Check whether embedding is available with a detailed reason on failure.

package/dist/llm/embedders/local.js

@@ -10,8 +10,9 @@
  * shared instance for the production code path.
  */
 import path from "node:path";
-import { getCacheDir } from "../../core/paths";
-import { warn } from "../../core/warn";
+import { getCacheDir } from "../../core/paths.js";
+import { warn } from "../../core/warn.js";
+import { getDirname, resolveModule } from "../../runtime.js";
 /**
  * Default local transformer model for embeddings.
  * `bge-small-en-v1.5` scores higher on MTEB benchmarks than the previous
@@ -169,31 +170,17 @@ function shouldRetryWithoutExplicitDtype(error) {
 }
 /**
  * Check whether the `@huggingface/transformers` package can be resolved.
- * Uses `Bun.resolveSync` so we never load the module (which would trigger
- * heavy WASM/model side-effects) just to test availability.
- *
- * Falls back to `require.resolve` when `Bun.resolveSync` is unavailable
- * (e.g. running under Node), so the function still works in mixed runtimes.
+ * Uses the runtime boundary's `resolveModule` so we never load the module
+ * (which would trigger heavy WASM/model side-effects) just to test
+ * availability. `resolveModule` uses `Bun.resolveSync` on Bun and
+ * `require.resolve` on Node.
  */
 export function isTransformersAvailable() {
     try {
-        if (typeof Bun !== "undefined" && typeof Bun.resolveSync === "function") {
-            Bun.resolveSync("@huggingface/transformers", import.meta.dir);
-            return true;
-        }
-    }
-    catch {
-        return false;
-    }
-    try {
-        const req = globalThis.require;
-        if (req && typeof req.resolve === "function") {
-            req.resolve("@huggingface/transformers");
-            return true;
-        }
+        resolveModule("@huggingface/transformers", getDirname(import.meta.url));
+        return true;
     }
     catch {
         return false;
     }
-    return false;
 }

package/dist/llm/embedders/remote.js

@@ -7,8 +7,8 @@
  * Calls the configured `/embeddings` endpoint and L2-normalizes the returned
  * vectors so the scoring pipeline's L2-to-cosine conversion is correct.
  */
-import { fetchWithTimeout, isHttpUrl } from "../../core/common";
-import { resolveSecret } from "../../core/config";
+import { fetchWithTimeout, isHttpUrl } from "../../core/common.js";
+import { resolveSecret } from "../../core/config/config.js";
 const DEFAULT_REMOTE_BATCH_SIZE = 100;
 /** Cheap token estimator: 4 chars ≈ 1 token. Used in verbose logging and error messages. */
 export function estimateTokenCount(text) {

package/dist/llm/embedders/types.js

@@ -32,4 +32,4 @@ export function cosineSimilarity(a, b) {
 }
 // Imported lazily to keep this types module dependency-free where possible;
 // `warn` is a thin printf wrapper so the cost is negligible.
-import { warn } from "../../core/warn";
+import { warn } from "../../core/warn.js";

package/dist/llm/graph-extract.js

@@ -21,10 +21,10 @@
  * straight through.
  */
 import userPromptTemplate from "../assets/prompts/graph-extract-user-prompt.md" with { type: "text" };
-import { toErrorMessage } from "../core/common";
-import { warn, warnVerbose } from "../core/warn";
-import { chatCompletion, parseEmbeddedJsonResponse } from "./client";
-import { tryLlmFeature } from "./feature-gate";
+import { toErrorMessage } from "../core/common.js";
+import { warn, warnVerbose } from "../core/warn.js";
+import { chatCompletion, LlmCallError, parseEmbeddedJsonResponse } from "./client.js";
+import { tryLlmFeature } from "./feature-gate.js";
 /**
  * Separator token used between assets in a batch prompt.
  * Chosen to be visually clear and unlikely to appear verbatim in asset bodies.
@@ -48,14 +48,22 @@ const USER_PROMPT_PREFIX = userPromptTemplate
 /**
  * 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).
  */
-function isContextSizeError(message) {
+export function isContextSizeError(message) {
     const lower = message.toLowerCase();
-    return (lower.includes("context size") ||
-        lower.includes("context length") ||
-        lower.includes("context_window") ||
-        lower.includes("prompt too long") ||
-        (lower.includes("exceeds") && lower.includes("context")));
+    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;
 }
 const GENERIC_ENTITIES = new Set([
     "agent",
@@ -529,6 +537,7 @@ export async function extractGraphFromBodies(llmConfig, bodies, signal, akmConfi
                 temperature: 0.1,
                 timeoutMs: llmConfig.timeoutMs,
                 signal,
+                onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
             });
             if (!raw)
                 return null;
@@ -671,7 +680,12 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
             const raw = await chatCompletion(llmConfig, [
                 { role: "system", content: SYSTEM_PROMPT },
                 { role: "user", content: userPrompt },
-            ], { temperature: 0.1, timeoutMs: llmConfig.timeoutMs, signal });
+            ], {
+                temperature: 0.1,
+                timeoutMs: llmConfig.timeoutMs,
+                signal,
+                onRetryAttempt: () => bumpTelemetry(options.telemetry, "retryAttempts"),
+            });
             if (!raw)
                 return empty();
             const parsed = parseEmbeddedJsonResponse(raw);
@@ -696,6 +710,11 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
                     `Consider increasing llm.contextLength in config.json.`);
                 return empty("context_limit", "failed");
             }
+            else if (err instanceof LlmCallError && err.code === "provider_html_error") {
+                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");
+            }
             else {
                 bumpTelemetry(options.telemetry, "failureCount");
                 warn(`graph extraction failed for asset; promptChars=${userPrompt.length}${formatContextHint(llmConfig)}: ${errMsg}`);
@@ -708,4 +727,4 @@ export async function extractGraphFromBody(llmConfig, body, signal, akmConfig, o
     });
 }
 // deduplicateGraph moved to src/indexer/graph-dedup.ts (pure utility, no LLM calls).
-export { deduplicateGraph } from "../indexer/graph-dedup";
+export { deduplicateGraph } from "../indexer/graph/graph-dedup.js";

package/dist/llm/index-passes.js

@@ -1,7 +1,7 @@
 // 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";
+import { getDefaultLlmConfig, getIndexPassConfig } from "../core/config/config.js";
 /**
  * Map a pass name (as used by callers — "memory", "graph", etc.) to the
  * matching key under `profiles.improve.default.processes`. Pass names with

package/dist/llm/memory-infer.js

@@ -18,10 +18,10 @@
  * the connection via `resolveIndexPassLLM("memory", config)` and pass it
  * straight through.
  */
-import { toErrorMessage } from "../core/common";
-import { warn } from "../core/warn";
-import { chatCompletion, parseEmbeddedJsonResponse } from "./client";
-import { tryLlmFeature } from "./feature-gate";
+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. " +
@@ -66,7 +66,7 @@ const DERIVED_MEMORY_JSON_SCHEMA = {
  * 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) {
+export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akmConfig, onFallback, telemetry, onRetryAttempt) {
     const trimmedBody = body.trim();
     if (!trimmedBody)
         return undefined;
@@ -81,6 +81,7 @@ export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akm
                 timeoutMs: llmConfig.timeoutMs,
                 signal,
                 responseSchema: DERIVED_MEMORY_JSON_SCHEMA,
+                onRetryAttempt,
             });
             if (!raw)
                 return undefined;
@@ -113,6 +114,12 @@ export async function compressMemoryToDerivedMemory(llmConfig, body, signal, akm
             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;
         }

package/dist/llm/metadata-enhance.js

@@ -1,8 +1,8 @@
 // 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";
+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.`;
 /**
  * Use an LLM to enhance a stash entry's metadata: improve description,