@ngockhoale/ukit 2.3.13 → 2.3.14

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.14 - 2026-09-11
+
+Vision-lane root cause, part 3 — the decisive one: the extractor could not see images in REAL
+Claude Code transcripts at all. Found by reproducing the failure against the user's own real
+session transcripts after they insisted the bug lived "right at the image" — grep proved the
+transcripts contained `"type":"image"` while every extraction returned `imageCount: 0`. The
+2.3.12/2.3.13 suites were green because the fixtures modeled an invented transcript shape.
+
+**P1 — real transcript image envelopes were invisible to the extractor.** Verified against
+real transcripts from four projects, Claude Code stores images in THREE shapes:
+
+- flat: `message.content[i] = { type: 'image', source: { type: 'base64', … } }` — the only
+  shape the pre-fix parser handled;
+- pasted: a top-level `attachment` envelope (`type: 'attachment'`,
+  `attachment.prompt[]` = content blocks) — every real pasted image lives here, NOT in
+  `message.content`; the pre-fix parser extracted nothing from any pasted image;
+- tool-returned: `message.content[i] = { type: 'tool_result', content: [ { type: 'image',
+  … } ] }` — screenshots coming back from tools nest one level down; also invisible.
+
+Fix: `extractImageBlocks()` now walks a bounded collector (depth ≤ 3) across
+`message.content[]`, nested `content[]` arrays inside blocks, and the top-level
+`attachment.prompt[]` / `attachment.content` envelopes. Same-base64 payloads across
+envelopes dedupe by sha as before. Real-data validation after the fix: the same four
+transcripts now extract valid images (PNG 2278×2154 from the paste envelope, JPEG 1400×884
+from a tool_result, PNG/JPEG from the flat shape), and a live analyst dispatch read the
+real pasted screenshot.
+
+Tests: `tests/handoff/cycle10/extract-image-contract.test.mjs` gains three cases whose
+fixtures copy the real envelope structures verbatim (RED pre-fix: `imageCount 0`), plus a
+cross-envelope dedupe pin. All cycle10 + cycle4 vision suites green.
+
 ## 2.3.13 - 2026-09-11
 
 Vision-lane root cause, part 2: the Codex model catalog could still deny the vision lane on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.3.13",
+  "version": "2.3.14",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/templates/.claude/ukit/index/extract-image.mjs

@@ -381,25 +381,64 @@ function readLines(filePath) {
   return raw.split('\n').filter((line) => line.trim().length > 0);
 }
 
+/**
+ * Deepest content-blocks nesting the collector walks. 1 covers the flat
+ * message.content[] / attachment.prompt[] arrays; 2 covers the real-world
+ * tool_result nesting (message.content[i].content[]); 3 is a cheap safety
+ * bound — deeper structures are not a Claude Code shape and are ignored.
+ */
+const MAX_BLOCK_WALK_DEPTH = 3;
+
+/**
+ * Collects base64 image blocks from one content-blocks array. Real Claude
+ * Code transcripts nest images in more than one place (verified against real
+ * session transcripts 2026-09-11 — the pre-fix parser only saw the flat
+ * shape and extracted NOTHING from real paste/tool-image traffic):
+ *   A. message.content[i] = { type: 'image', source: { type: 'base64', … } }
+ *   C. message.content[i] = { type: 'tool_result', content: [ { type: 'image', … } ] }
+ * Blocks that carry their own `content` array (tool_result etc.) are walked
+ * one level deeper, bounded by MAX_BLOCK_WALK_DEPTH.
+ */
+function collectImageBlocksFromContent(content, lineIndex, blocks, depth) {
+  if (!Array.isArray(content) || depth > MAX_BLOCK_WALK_DEPTH) return;
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    if (block.type === 'image') {
+      const source = block.source;
+      if (!source || source.type !== 'base64') continue;
+      const mediaType = source.media_type;
+      const data = source.data;
+      if (typeof mediaType !== 'string' || typeof data !== 'string' || !data) continue;
+      blocks.push({ mediaType, data, lineIndex });
+    } else if (Array.isArray(block.content)) {
+      collectImageBlocksFromContent(block.content, lineIndex, blocks, depth + 1);
+    }
+  }
+}
+
 /**
  * Parses each JSONL line independently. A malformed line is skipped via its
  * own try/catch and never throws out to the caller.
+ *
+ * Envelope shapes collected per line (real-transcript evidence 2026-09-11):
+ *   A/C. the API message envelope — flat image blocks, plus tool_result
+ *        blocks that nest theirs one level down (see the collector above).
+ *   B.   pasted images arrive in a TOP-LEVEL attachment envelope, NOT in
+ *        message.content: attachment.prompt[] is the content-blocks array
+ *        (attachment.content accepted defensively for the same reason).
+ * The same payload appearing in two envelopes (attachment + the later user
+ * message) dedupes by sha in selectImages().
  */
 function extractImageBlocks(lines) {
   const blocks = [];
   for (let i = 0; i < lines.length; i += 1) {
     try {
       const obj = JSON.parse(lines[i]);
-      const content = obj?.message?.content;
-      if (!Array.isArray(content)) continue;
-      for (const block of content) {
-        if (block?.type !== 'image') continue;
-        const source = block.source;
-        if (!source || source.type !== 'base64') continue;
-        const mediaType = source.media_type;
-        const data = source.data;
-        if (typeof mediaType !== 'string' || typeof data !== 'string' || !data) continue;
-        blocks.push({ mediaType, data, lineIndex: i });
+      collectImageBlocksFromContent(obj?.message?.content, i, blocks, 1);
+      const attachment = obj?.attachment;
+      if (attachment && typeof attachment === 'object') {
+        collectImageBlocksFromContent(attachment.prompt, i, blocks, 1);
+        collectImageBlocksFromContent(attachment.content, i, blocks, 1);
       }
     } catch {
       // malformed line: skip and continue