@ngockhoale/ukit 2.3.13 → 2.3.15

package/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 All notable changes to UKit are documented here.
 
+## 2.3.15 - 2026-09-11
+
+Vision-lane root cause, part 4 — native-first dispatch order. Found by mining the user's own
+failing sessions across four real projects (UnicDB, VSDB, BAGuide, AI-Gateway): the API `model`
+field in the transcripts proved failed specialist dispatches landed on `glm-5-turbo` / lite lanes
+(self-reported `MODEL: unic-lite`, `STATUS: WRONG_MODEL`) while the same sessions' main Claude
+lanes read images fine (`STATUS: OK` ×14 in one transcript). Two stacked defects:
+
+- **No fallback when the specialist fails.** The honored-lane hint ordered the parent to dispatch
+  `ukit-vision-analyst` and simply continue; when the gateway routed the alias to a backend that
+  cannot receive the image through the Read tool_result, the analyst returned `WRONG_MODEL` and
+  the image ended up unread even though the parent could have read it natively. The hint now
+  verifies the parent's own vision FIRST (step 2: Read the materialized files yourself, write the
+  receipts, do NOT dispatch), dispatches the specialist only when the parent's own Read yields no
+  image (step 3), and defines the fallback: on `WRONG_MODEL`/`NO_IMAGE` re-read natively, analyse
+  from your own view for pasted images, and never fabricate when no reader can see it (step 4).
+- **Refusal by name instead of by probe.** The omp analyst template mandated refusing *before
+  touching any image* when the runtime model could not be confirmed vision-capable — field
+  transcripts show exactly this refusal (`I must refuse to open, describe, or guess`). Both agent
+  templates now decide ONLY by the first image Read (the probe): a backend that self-identifies as
+  `glm-5-turbo`/`MiniMax-M3`/a lite lane does not license refusal when the probe actually shows
+  the image; a vision-sounding name with a failed probe is still `WRONG_MODEL`.
+
+Unchanged doctrine: never guess at image contents — the fix removes the two paths that turned
+"don't guess" into "don't read". omp mirrors synced. TDD: `vision-router-hint` tests 13-14 and
+`vision-agent` test 13 written RED first, then GREEN; all vision suites pass.
+
+## 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.15",
   "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/agents/ukit-vision-analyst.md

@@ -27,6 +27,12 @@ demonstrated, never assumed from a name:
   actually give you the image (error, empty result, or you can only see text you were told about),
   you are not vision-capable right now: emit `STATUS: WRONG_MODEL` and stop immediately. Do not
   describe, summarise, or guess at any image content.
+- Decide ONLY by the probe result — never by the lane's name. A mapping that sounds non-visual
+  (e.g. your environment says you are a lite lane) does NOT license refusal when the probe
+  actually shows you the image: if you can see it, you are vision-capable right now — report the
+  mapping you actually ran on in `MODEL:` and continue. Conversely, a vision-sounding name with a
+  failed probe is still `STATUS: WRONG_MODEL`. Refusing by name without probing was the exact
+  failure that left images unread in the field.
 - Never guess at image contents. A non-visual "analysis" is worse than no analysis at all, because
   it looks authoritative while being fabricated. Refusing loudly is always safer than guessing
   quietly.

package/templates/.claude/hooks/vision-router.sh

@@ -283,31 +283,34 @@ const { pathToFileURL } = require('url');
   }
 
   // Lane honored (or unverified — missing aliasAvailable defaults to today's
-  // unic-vision dispatch). Capability-framed, never provider identity: the
-  // remedy is "don't guess — use a verified reader", which holds whether the
-  // active model reads images natively or hands off to the specialist.
+  // dispatch). NATIVE-FIRST ordering (2026-09-11): field evidence showed
+  // specialist dispatches landing on gateways/backends that could not return
+  // the image through the Read tool_result (STATUS: WRONG_MODEL, self-reported
+  // unic-lite / glm-5-turbo) while the parent — usually a Claude lane — could
+  // have read the image itself. So the hint verifies the parent's own vision
+  // FIRST by reading the materialized file, dispatches the specialist only as
+  // a fallback, and defines a fallback when the specialist fails anyway —
+  // an image must never end up unread just because one lane failed.
   const unicNote = (unicMode === true && gatewayResult?.visionModel)
     ? `  (UNIC gateway active — ${gatewayResult.visionModel} routes through it.)`
     : '';
 
-  const reasonLines = [
-    'Advisory: never guess at image contents. If the active model has VERIFIED native',
-    'vision for these images it may read them directly; otherwise dispatch the specialist',
-    'before relying on them:',
-  ];
-
   const lines = [
     `UKIT VISION ROUTE — new image input detected (${cases.join(', ')}).`,
-    ...reasonLines,
+    'Advisory: never guess at image contents. Verify a real reader before relying on them:',
     `  1. ${materializeCmd}`,
-    '     Materialize the images to disk. With --session the extractor targets the',
-    '     PARENT transcript explicitly, so a subagent spawn cannot drop the image.',
-    '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]',
-    '     Send the ABSOLUTE paths from images[].path as TEXT (subagents do NOT inherit',
-    '     image blocks; they can only Read files). Include the task envelope: the ORIGINAL',
-    '     user prompt verbatim, the visual question, and the task goal — the analyst must',
-    '     know what the images are FOR.',
-    '  3. Continue the real task using the analyst\'s OBSERVATIONS + INFERENCES.',
+    '     Materialize to disk (--session targets the PARENT transcript, so a subagent',
+    '     spawn cannot drop the image).',
+    '  2. Read each ABSOLUTE path in images[].path YOURSELF, in the main session. If',
+    '     the image actually arrives you have VERIFIED native vision: analyse it and',
+    '     write receipts (analyzed-<sha>.json; sha/sessionId from the extractor output;',
+    '     model = your actual model). No dispatch.',
+    '  3. Only if your own Read shows no image: Agent(subagent_type: "ukit-vision-analyst")',
+    '     [model: unic-vision] — send paths as TEXT (subagents do NOT inherit image',
+    '     blocks) plus the task envelope: original prompt, visual question, goal.',
+    '  4. Specialist answers WRONG_MODEL or NO_IMAGE → do not leave the image unread:',
+    '     re-Read yourself; for a pasted image you can see directly, analyse from your',
+    '     own view. No reader can see it → say so plainly, never fabricate.',
   ];
   if (sessionId) {
     lines.push(`  Markers armed under sessionId: ${sessionId} (receipts: analyzed-<sha>.json).`);

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

package/templates/.omp/agents/ukit-vision-analyst.md

@@ -17,19 +17,23 @@ actually in them. You never write, edit, or refactor product code — you analys
 - Stay end-user-invisible: this lane is internal UKit orchestration, not something end users invoke
   by name.
 
-## 2. Model self-check — first action, before touching any image
-
-Before reading any image, determine the model you are actually running on right now.
-
-- Vision-capable means: `unic-vision`, or — when `unicMode` is off — whatever
-  `modelTiers.vision.fallbackModel` resolves to per
-  `node .claude/ukit/index/unic-gateway.mjs --json`.
-- If you cannot confirm you are running on a vision-capable model, you must **refuse**: emit
-  `STATUS: WRONG_MODEL` in the output block below and stop immediately. Do not open, describe, or
-  guess at any image content.
-- Never guess at image contents. A wrong-model "analysis" is worse than no analysis at all,
-  because it looks authoritative while being fabricated. Refusing loudly is always safer than
-  guessing quietly.
+## 2. Capability self-check — the first image read is the probe
+
+Model names are gateway mappings whose backend can change at any time, so capability is
+demonstrated, never assumed from a name:
+
+- Your first `read` of an image file doubles as the capability probe. If the tool result does not
+  actually give you the image (error, empty result, or you can only see text you were told about),
+  you are not vision-capable right now: emit `STATUS: WRONG_MODEL` in the output block below and
+  stop immediately. Do not describe, summarise, or guess at any image content.
+- Decide ONLY by the probe result — never by the lane's name. A backend that self-identifies as
+  something else (e.g. `glm-5-turbo`, `MiniMax-M3`, a lite lane) does NOT license refusal when the
+  probe actually shows you the image: if you can see it, you are vision-capable right now — report
+  what you actually ran on in `MODEL:` and continue. Refusing by name without probing was the
+  exact failure that left images unread in the field.
+- Never guess at image contents. A non-visual "analysis" is worse than no analysis at all, because
+  it looks authoritative while being fabricated. Refusing loudly is always safer than guessing
+  quietly.
 
 ## 3. Input protocol (priority order)