akm-cli 0.9.0-beta.44 → 0.9.0-beta.45

package/dist/commands/health.js

@@ -134,6 +134,7 @@ function createUnknownImproveMetrics() {
             failures: 0,
             htmlErrors: 0,
             retryAttempts: 0,
+            nonArrayBatchFailures: 0,
             durationMs: 0,
         },
         sessionExtraction: {
@@ -440,6 +441,7 @@ function projectRunMetrics(result) {
             metrics.graphExtraction.failures += toFiniteNumber(telemetry.failureCount);
             metrics.graphExtraction.htmlErrors += toFiniteNumber(telemetry.htmlErrorCount);
             metrics.graphExtraction.retryAttempts += toFiniteNumber(telemetry.retryAttempts);
+            metrics.graphExtraction.nonArrayBatchFailures += toFiniteNumber(telemetry.nonArrayBatchFailures);
         }
     }
     metrics.graphExtraction.durationMs += toFiniteNumber(result.graphExtractionDurationMs);
@@ -587,6 +589,7 @@ function mergeImproveMetrics(dst, src) {
     dst.graphExtraction.truncations += src.graphExtraction.truncations;
     dst.graphExtraction.failures += src.graphExtraction.failures;
     dst.graphExtraction.htmlErrors += src.graphExtraction.htmlErrors;
+    dst.graphExtraction.nonArrayBatchFailures += src.graphExtraction.nonArrayBatchFailures;
     dst.graphExtraction.durationMs += src.graphExtraction.durationMs;
     dst.sessionExtraction.sessionsScanned += src.sessionExtraction.sessionsScanned;
     dst.sessionExtraction.sessionsExtracted += src.sessionExtraction.sessionsExtracted;
@@ -990,6 +993,7 @@ const INTERESTING_DELTA_PATHS = [
     "improve.graphExtraction.cacheHitRate",
     "improve.graphExtraction.failures",
     "improve.graphExtraction.htmlErrors",
+    "improve.graphExtraction.nonArrayBatchFailures",
     "improve.sessionExtraction.sessionsScanned",
     "improve.sessionExtraction.proposalsCreated",
     "improve.autoAccept.promoted",
@@ -1655,6 +1659,7 @@ export function renderWindowCompareMd(windows, deltas) {
         "improve.actions.reflect.failed",
         "improve.actions.distill.llmFailed",
         "improve.graphExtraction.failures",
+        "improve.graphExtraction.nonArrayBatchFailures",
         "improve.wallTime.medianMs",
         "improve.wallTime.p95Ms",
         "improve.memoryInference.skippedNoFacts",

package/dist/core/parse.js

@@ -98,16 +98,24 @@ export function parseJsonResponse(raw) {
  * balanced `{ }` or `[ ]` structure in the text and attempts to parse that
  * substring. Returns `undefined` if no valid JSON structure is found.
  *
- * Non-array results are preferred: if a `{…}` object is found first, it is
- * returned immediately. Arrays (`[…]`) are captured as a fallback and
- * returned only when no object was found.
+ * Shape preference is controlled by {@link ParseEmbeddedJsonOptions.expect}:
+ * - `"any"` (default): non-array results are preferred — a `{…}` object found
+ *   first is returned immediately; arrays (`[…]`) are a fallback.
+ * - `"array"`: only top-level arrays are returned. The direct parse is
+ *   accepted only if it is an array, and the scanner returns the first
+ *   balanced `[…]` while skipping `{…}` openers entirely.
  */
-export function parseEmbeddedJsonResponse(raw) {
+export function parseEmbeddedJsonResponse(raw, options) {
+    const expectArray = options?.expect === "array";
     const direct = parseJsonResponse(raw);
-    if (direct !== undefined)
+    if (direct !== undefined && (!expectArray || Array.isArray(direct)))
         return direct;
     const text = escapeJsonStringControls(stripCodeFences(stripThinkBlocks(raw)));
     let arrayFallback;
+    // Scan only *top-level* balanced structures: once a `{…}`/`[…]` is matched we
+    // jump `start` past its closing bracket rather than re-scanning its interior.
+    // This keeps array mode from salvaging an array *nested inside* a leading
+    // object (e.g. the `entities` array of a bare `{entities,relations}` object).
     for (let start = 0; start < text.length; start++) {
         const opener = text[start];
         if (opener !== "{" && opener !== "[")
@@ -116,6 +124,7 @@ export function parseEmbeddedJsonResponse(raw) {
         let depth = 0;
         let inString = false;
         let escaped = false;
+        let end = -1;
         for (let i = start; i < text.length; i++) {
             const ch = text[i];
             if (inString) {
@@ -139,20 +148,31 @@ export function parseEmbeddedJsonResponse(raw) {
             if (ch === closer) {
                 depth -= 1;
                 if (depth === 0) {
-                    try {
-                        const parsed = JSON.parse(text.slice(start, i + 1));
-                        if (!Array.isArray(parsed)) {
-                            return parsed;
-                        }
-                        arrayFallback ??= parsed;
-                        break;
-                    }
-                    catch {
-                        break;
-                    }
+                    end = i;
+                    break;
                 }
             }
         }
+        if (end === -1)
+            continue; // never balanced — let the next opener try
+        try {
+            const parsed = JSON.parse(text.slice(start, end + 1));
+            if (Array.isArray(parsed)) {
+                // First valid array wins in array mode; in "any" mode it is the
+                // fallback returned only if no object is found.
+                if (expectArray)
+                    return parsed;
+                arrayFallback ??= parsed;
+            }
+            else if (!expectArray) {
+                return parsed;
+            }
+            // Skip past this balanced structure so we don't descend into it.
+            start = end;
+        }
+        catch {
+            // Malformed candidate — advance one char and try the next opener.
+        }
     }
     return arrayFallback;
 }

package/dist/indexer/graph/graph-extraction.js

@@ -372,6 +372,7 @@ export async function runGraphExtractionPass(ctx) {
         failureCount: 0,
         htmlErrorCount: 0,
         retryAttempts: 0,
+        nonArrayBatchFailures: 0,
     };
     const canReusePreviousGraph = previousGraph.telemetry?.extractorId === extractorId;
     const runtimeTelemetry = {
@@ -625,6 +626,7 @@ export async function runGraphExtractionPass(ctx) {
     telemetry.failureCount = runtimeTelemetry.failureCount ?? 0;
     telemetry.htmlErrorCount = runtimeTelemetry.htmlErrorCount ?? 0;
     telemetry.retryAttempts = runtimeTelemetry.retryAttempts ?? 0;
+    telemetry.nonArrayBatchFailures = runtimeTelemetry.nonArrayBatchFailures ?? 0;
     const qualityConsidered = mergedNodes.length;
     const qualityExtracted = mergedNodes.filter((node) => node.status === "extracted" && node.entities.length > 0).length;
     const quality = computeGraphQualityTelemetry(qualityConsidered, qualityExtracted, deduped.entities.length, deduped.relations.length);

package/dist/llm/graph-extract.js

@@ -433,6 +433,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");
@@ -542,7 +554,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");
@@ -552,8 +578,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.0-beta.44",
+  "version": "0.9.0-beta.45",
   "type": "module",
   "description": "akm (Agent Knowledge Management) — A package manager for AI agent skills, commands, tools, and knowledge. Works with Claude Code, OpenCode, Cursor, and any AI coding assistant.",
   "keywords": [