akm-cli 0.9.0-beta.5 → 0.9.0-beta.50

package/dist/integrations/harnesses/opencode-sdk/index.js

@@ -5,7 +5,7 @@
  * OpenCode SDK harness (#564).
  *
  * Per-harness barrel for the SDK-mode dispatch path:
- *   - agent runner → ./sdk-runner.ts (runOpencodeSdk / runAgentSdk)
+ *   - agent runner → ./sdk-runner.ts (runOpencodeSdk)
  *
  * It also defines {@link OpencodeSdkHarness}, the {@link AkmHarness} descriptor
  * that `HARNESS_REGISTRY` registers.
@@ -17,7 +17,7 @@
  * names. Canonical id is `'opencode-sdk'` with no alias.
  */
 import { BaseHarness } from "../types.js";
-export { closeServer, runAgentSdk, runOpencodeSdk } from "./sdk-runner.js";
+export { closeServer, runOpencodeSdk } from "./sdk-runner.js";
 function caps(c) {
     return {
         sessionLogs: false,

package/dist/integrations/harnesses/opencode-sdk/sdk-runner.js

@@ -230,5 +230,3 @@ export async function runOpencodeSdk(profile, prompt, opts = {}, llmConfig) {
         await client.session.delete({ path: { id: sessionId } }).catch(() => { });
     }
 }
-/** @deprecated Use {@link runOpencodeSdk} instead. */
-export const runAgentSdk = runOpencodeSdk;

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

@@ -28,6 +28,22 @@ const ERROR_PATTERNS = /error|failed|exception|cannot|undefined|null pointer|ENO
 export function getAvailableHarnesses() {
     return HARNESSES.filter((harness) => harness.isAvailable());
 }
+/**
+ * Map each available harness to its `{ harnessName, roots }` watch target,
+ * skipping harnesses that expose no roots (absent `watchRoots()` or an empty
+ * result). This is the one stable entry point the watcher uses so it never
+ * reaches into providers directly.
+ */
+export function getWatchTargets() {
+    const targets = [];
+    for (const harness of getAvailableHarnesses()) {
+        const roots = harness.watchRoots?.() ?? [];
+        if (roots.length === 0)
+            continue;
+        targets.push({ harnessName: harness.name, roots });
+    }
+    return targets;
+}
 export function normalizeSessionTopic(text) {
     const normalized = text.replace(/\s+/g, " ").trim().toLowerCase();
     if (normalized.length < 10)

package/dist/llm/client.js

@@ -103,35 +103,65 @@ 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.
+ * 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).
+ *
+ * Canonical home: `graph-extract.ts` re-exports this so the index-pass
+ * graph extractor and the retry classifier (`isRetryable`) share one
+ * definition — retrying a context overflow cannot shrink the input, so it
+ * must never be retried.
  */
-function looksLikeContextOverflow(message) {
+export function isContextSizeError(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")));
+    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;
 }
 /**
  * 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.
+ * `network_error` whose message looks like a transient connection drop.
+ * NOT retryable: 4xx, `rate_limited` (429), `timeout`, `parse_error`, and
+ * context-overflow-classified errors.
+ *
+ * The connection-drop heuristic covers the substrings emitted across runtimes
+ * for a mid-flight socket close:
+ *  - `ECONNRESET` / `EPIPE` — Node/libuv socket reset codes
+ *  - `fetch failed` — undici's generic wrapper message
+ *  - `socket connection was closed` — Bun's message for a dropped connection
+ *    (e.g. "The socket connection was closed unexpectedly.")
+ *  - `terminated` / `other side closed` — undici's phrasings for the same
+ *
+ * These all describe a transient transport failure where a second attempt can
+ * legitimately succeed, which is exactly the case a single bounded retry is
+ * meant to absorb. Before this list was widened, Bun's "socket connection was
+ * closed unexpectedly" fell through unretried and surfaced as a recurring
+ * failure in the improve/reflect and capability-probe flows.
  */
 function isRetryable(err) {
-    if (looksLikeContextOverflow(err.message))
+    if (isContextSizeError(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 (lower.includes("econnreset") ||
+            lower.includes("epipe") ||
+            lower.includes("fetch failed") ||
+            lower.includes("socket connection was closed") ||
+            lower.includes("terminated") ||
+            lower.includes("other side closed"));
     }
     return false;
 }

package/dist/llm/embedder.js

@@ -2,7 +2,8 @@
 // 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.js";
-import { isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
+import { DETERMINISTIC_EMBED_MODEL_ID, deterministicEmbed, isDeterministicEmbedEnabled, } from "./embedders/deterministic.js";
+import { DEFAULT_LOCAL_MODEL, isTransformersAvailable, LocalEmbedder } from "./embedders/local.js";
 import { hasRemoteEndpoint, RemoteEmbedder } from "./embedders/remote.js";
 // ── Re-exports (public API) ─────────────────────────────────────────────────
 export { clearEmbeddingCache } from "./embedders/cache.js";
@@ -39,6 +40,10 @@ export function resetLocalEmbedder() {
  * and embedding config. Repeated identical queries return the cached vector.
  */
 export async function embed(text, embeddingConfig, signal) {
+    // Deterministic mode (env-gated, test/bench only): model-free, stable.
+    if (isDeterministicEmbedEnabled()) {
+        return deterministicEmbed(text);
+    }
     const key = embedCacheKey(text, embeddingConfig);
     const cached = getCachedEmbedding(key);
     if (cached)
@@ -52,16 +57,26 @@ export async function embed(text, embeddingConfig, signal) {
 /**
  * Generate embeddings for multiple texts in batch.
  * Uses the OpenAI-compatible batch API for remote endpoints (batches of 100).
- * Falls back to sequential embedding for the local transformer pipeline.
+ * Uses the LocalEmbedder.embedBatch path for the local transformer pipeline,
+ * which processes texts in chunks of 32 for genuine batched inference.
  */
 export async function embedBatch(texts, embeddingConfig, signal) {
     if (texts.length === 0)
         return [];
+    // Deterministic mode (env-gated, test/bench only): model-free, stable.
+    if (isDeterministicEmbedEnabled()) {
+        return texts.map((t) => deterministicEmbed(t));
+    }
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         return new RemoteEmbedder(embeddingConfig).embedBatch(texts, signal);
     }
-    // Local transformer: process sequentially (pipeline handles one at a time)
+    // Local transformer: use the batched path (chunks of 32 via LocalEmbedder).
+    // When a localModel override is set we cannot share the singleton (which uses
+    // the default model), so fall back to per-text embedWithModel in that case.
     const localModel = embeddingConfig?.localModel;
+    if (!localModel) {
+        return getLocalEmbedder().embedBatch(texts, signal);
+    }
     const results = [];
     for (const text of texts) {
         if (signal?.aborted) {
@@ -77,11 +92,35 @@ export async function embedBatch(texts, embeddingConfig, signal) {
 // facade and its `@huggingface/transformers` import chain. Re-export
 // preserves the existing public API.
 export { cosineSimilarity } from "./embedders/types.js";
+// ── Model ID resolution ─────────────────────────────────────────────────────
+/**
+ * Derive a stable string identifier for the embedding model in use.
+ * This is the `model_id` stored in `body_embeddings` (and used for the
+ * drop-all-on-mismatch purge when the model changes).
+ *
+ * Rules:
+ *   - Remote endpoint: use `config.model` (the API-level model name).
+ *   - Local transformers: use `config.localModel ?? DEFAULT_LOCAL_MODEL`.
+ *   - No config: use `DEFAULT_LOCAL_MODEL` (the shared singleton model).
+ */
+export function resolveEmbeddingModelId(embeddingConfig) {
+    if (isDeterministicEmbedEnabled())
+        return DETERMINISTIC_EMBED_MODEL_ID;
+    if (!embeddingConfig)
+        return DEFAULT_LOCAL_MODEL;
+    if (hasRemoteEndpoint(embeddingConfig))
+        return embeddingConfig.model ?? "remote";
+    return embeddingConfig.localModel ?? DEFAULT_LOCAL_MODEL;
+}
 // ── Availability check ──────────────────────────────────────────────────────
 /**
  * Check whether embedding is available with a detailed reason on failure.
  */
 export async function checkEmbeddingAvailability(embeddingConfig) {
+    // Deterministic mode (env-gated): always available — no model, no network.
+    if (isDeterministicEmbedEnabled()) {
+        return { available: true };
+    }
     if (embeddingConfig && hasRemoteEndpoint(embeddingConfig)) {
         try {
             await new RemoteEmbedder(embeddingConfig).embed("test");

package/dist/llm/embedders/deterministic.js

@@ -0,0 +1,66 @@
+// 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/.
+/** Env var that switches the whole embedding facade into deterministic mode. */
+export const DETERMINISTIC_EMBED_ENV = "AKM_EMBED_DETERMINISTIC";
+/**
+ * Vector width. Matches the default local model (`bge-small`, 384 dims) so the
+ * index DB's embedding column and sqlite-vec table dimensions line up without
+ * any extra config.
+ */
+export const DETERMINISTIC_EMBED_DIM = 384;
+/**
+ * Stable model id reported for deterministic mode. Used as the embedding
+ * `model_id` and folded into the provider fingerprint so a deterministic index
+ * is never confused with a real-model index (and vice versa).
+ */
+export const DETERMINISTIC_EMBED_MODEL_ID = "akm-deterministic-hash-v1";
+/** True when deterministic embedding is enabled via env. */
+export function isDeterministicEmbedEnabled() {
+    return process.env[DETERMINISTIC_EMBED_ENV] === "1";
+}
+/** FNV-1a 32-bit hash. Platform- and version-stable. */
+function fnv1a(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        // 32-bit FNV prime multiply via shifts to stay in uint32.
+        h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0;
+    }
+    return h >>> 0;
+}
+/** Lowercase, split on non-alphanumeric, drop empties. */
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length > 0);
+}
+/**
+ * Deterministically embed `text` into a unit-length vector of width `dim`
+ * using feature hashing. Empty / token-less input returns a fixed unit
+ * vector so cosine similarity never sees a zero vector (NaN guard).
+ */
+export function deterministicEmbed(text, dim = DETERMINISTIC_EMBED_DIM) {
+    const vec = new Array(dim).fill(0);
+    const tokens = tokenize(text);
+    for (const tok of tokens) {
+        const h = fnv1a(tok);
+        const idx = h % dim;
+        // Use a higher bit for the sign so it is independent of the bucket index.
+        const sign = (h >>> 16) & 1 ? 1 : -1;
+        vec[idx] += sign;
+    }
+    let norm = 0;
+    for (const v of vec)
+        norm += v * v;
+    norm = Math.sqrt(norm);
+    if (norm === 0) {
+        // No usable tokens — return a fixed, stable unit vector.
+        vec[0] = 1;
+        return vec;
+    }
+    for (let i = 0; i < dim; i++)
+        vec[i] /= norm;
+    return vec;
+}

package/dist/llm/embedders/local.js

@@ -19,8 +19,24 @@ import { getDirname, resolveModule } from "../../runtime.js";
  * `all-MiniLM-L6-v2` at the same 384-dimension footprint.
  */
 export const DEFAULT_LOCAL_MODEL = "Xenova/bge-small-en-v1.5";
+/** Type-guard: true when the value looks like a batch Tensor (has .dims). */
+function isBatchTensor(v) {
+    return (v !== null &&
+        typeof v === "object" &&
+        "data" in v &&
+        "dims" in v &&
+        Array.isArray(v.dims) &&
+        v.dims.length >= 2);
+}
 const LOCAL_EMBEDDER_DTYPE = "fp32";
 const LOCAL_EMBEDDER_FALLBACK_DTYPE = "auto";
+/**
+ * Maximum texts per batch for the local transformers pipeline. The pipeline
+ * can run genuine batched inference over a string array; 32 is a safe default
+ * that fits well inside most model context budgets while providing 10–50×
+ * throughput improvement over one-at-a-time calls on the cold minority.
+ */
+const LOCAL_BATCH_SIZE = 32;
 /**
  * Return the local model name that will be used for embedding.
  * When `overrideModel` is provided it takes precedence; otherwise
@@ -77,15 +93,63 @@ export class LocalEmbedder {
         }
         return this.embedWithModel(text, this.defaultModel);
     }
+    /**
+     * Embed a batch of texts. Processes in chunks of `LOCAL_BATCH_SIZE` (32) so
+     * the transformers pipeline can run genuine batched inference rather than one
+     * call per text. Falls back to one-at-a-time if the pipeline does not support
+     * array input (older versions of @huggingface/transformers). Each chunk is
+     * checked against the AbortSignal between calls.
+     */
     async embedBatch(texts, signal) {
         if (texts.length === 0)
             return [];
+        if (signal?.aborted) {
+            throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
+        }
+        const pipeline = await this.getPipeline(this.defaultModel);
         const results = [];
-        for (const text of texts) {
+        for (let i = 0; i < texts.length; i += LOCAL_BATCH_SIZE) {
             if (signal?.aborted) {
                 throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
             }
-            results.push(await this.embedWithModel(text, this.defaultModel));
+            const chunk = texts.slice(i, i + LOCAL_BATCH_SIZE);
+            try {
+                // @huggingface/transformers feature-extraction pipeline accepts a
+                // string[] and returns a batch Tensor (NOT an Array<{data}>).
+                // The Tensor has .data (flat Float32Array, length = batch * dim) and
+                // .dims = [batch, dim]. Slice .data into per-row vectors using .dims.
+                const batchResult = await pipeline(chunk, {
+                    pooling: "mean",
+                    normalize: true,
+                });
+                if (isBatchTensor(batchResult)) {
+                    const dim = batchResult.dims[1];
+                    for (let row = 0; row < chunk.length; row++) {
+                        results.push(Array.from(batchResult.data.subarray(row * dim, (row + 1) * dim)));
+                    }
+                }
+                else if (Array.isArray(batchResult)) {
+                    // Older versions of @huggingface/transformers returned Array<{data}>.
+                    for (const r of batchResult) {
+                        results.push(Array.from(r.data));
+                    }
+                }
+                else {
+                    // Single-text result returned for a chunk — should not happen for
+                    // string[] input, but handle defensively.
+                    throw new Error("unexpected pipeline return shape for batch input");
+                }
+            }
+            catch {
+                // Fallback: process one-at-a-time (older pipeline versions or mismatched
+                // return type). Fail-open per text: a single failure aborts the chunk.
+                for (const text of chunk) {
+                    if (signal?.aborted) {
+                        throw signal.reason instanceof Error ? signal.reason : new Error("embedding interrupted");
+                    }
+                    results.push(await this.embedWithModel(text, this.defaultModel));
+                }
+            }
         }
         return results;
     }

package/dist/llm/feature-gate.js

@@ -30,10 +30,14 @@ const FEATURE_LOCATION = {
     proposal_quality_gate: (cfg) => cfg.profiles?.improve?.default?.processes?.reflect?.qualityGate?.enabled ?? false,
     // Legacy default: false
     memory_contradiction_detection: (cfg) => cfg.profiles?.improve?.default?.processes?.consolidate?.contradictionDetection?.enabled ?? false,
-    // Default: true. Session extraction replaces the akm-plugin checkpoint hook
-    // and is the primary path for capturing durable signal from real sessions.
-    // Opt out via `profiles.improve.default.processes.extract.enabled: false`.
-    session_extraction: (cfg) => cfg.profiles?.improve?.default?.processes?.extract?.enabled ?? true,
+    // Always on at the LLM-wrapper level. Enablement is decided ONCE at the
+    // extract entry point (`akmExtract`): the `extract.enabled` process toggle
+    // gates extract as a STAGE of `akm improve` (the active improve profile, per
+    // #593/#594), while an explicit `akm extract` command always runs. Gating the
+    // inner LLM calls on `default.processes.extract.enabled` here was a footgun —
+    // dropping extract from the daily improve profile silently disabled the
+    // standalone `akm extract` command. (cfg unused — kept for resolver signature.)
+    session_extraction: (_cfg) => true,
 };
 /**
  * Pure predicate: is the named feature gate enabled in `config`?

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,
     });
 }