@ngockhoale/ukit 1.6.4 → 1.6.5

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

@@ -0,0 +1,155 @@
+#!/bin/bash
+# UserPromptSubmit hook: detect image input (pasted / local path / URL) and arm the
+# TASK-008 write gate by writing pending-<sha>.json markers via extract-image.mjs.
+#
+# FAILS OPEN, unconditionally: this hook must never block the user's prompt. Any
+# failure (malformed stdin, missing extractor, node crash) degrades to "no hint,
+# no markers" and exit 0. This is the deliberate opposite of the TASK-008 gate,
+# which fails closed on Edit/Write.
+#
+# Detection only — never decodes an image, never writes an image file. Marker
+# writing is delegated entirely to `extract-image.mjs --mark-pending`; this hook
+# never computes a sha itself (PLAN §3.1).
+#
+# Runs on EVERY prompt, 8s budget: one shell-out to extract-image.mjs
+# --detect --mark-pending --json, no decoding.
+
+INPUT=$(cat)
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+
+INPUT="$INPUT" PROJECT_ROOT="$PROJECT_ROOT" node <<'NODE' || true
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { pathToFileURL } = require('url');
+
+(async () => {
+  const payload = (() => {
+    try {
+      const parsed = JSON.parse(process.env.INPUT || '');
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  })();
+  const projectRoot = process.env.PROJECT_ROOT;
+
+  function extractPromptText(p) {
+    const candidates = [p?.prompt, p?.user_prompt, p?.text];
+    for (const candidate of candidates) {
+      if (typeof candidate === 'string' && candidate.trim()) return candidate;
+    }
+    return '';
+  }
+
+  const promptText = extractPromptText(payload);
+
+  // URL images are checked first and stripped out so the local-path regex never
+  // re-matches the tail of a URL (case c is a hint-only lane — no download here).
+  const URL_IMAGE_RE = /https?:\/\/\S+\.(?:png|jpe?g|gif|webp)\b/gi;
+  const LOCAL_PATH_RE = /\S+\.(?:png|jpe?g|gif|webp|bmp)\b/gi;
+
+  const urlMatches = promptText.match(URL_IMAGE_RE) || [];
+  const textWithoutUrls = promptText.replace(URL_IMAGE_RE, ' ');
+  const localMatches = textWithoutUrls.match(LOCAL_PATH_RE) || [];
+
+  // Shell out to the single owner of image detection + marker writing. Runs on every
+  // prompt (cheap: --detect --mark-pending, never decodes). All three input forms are
+  // armed here, not just pasted images: a path or URL that only produced hint text would
+  // leave Edit/Write ungated, which is exactly the "analyse blind" case this cycle exists
+  // to prevent. --ref hashes a local file's bytes / a URL string inside the extractor.
+  let markedPasted = 0;
+  let markedPath = 0;
+  let markedUrl = 0;
+  const extractorPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'extract-image.mjs');
+  if (fs.existsSync(extractorPath)) {
+    const args = [extractorPath, '--detect', '--mark-pending', '--json'];
+    if (typeof payload?.transcript_path === 'string' && payload.transcript_path.trim()) {
+      args.push('--session', payload.transcript_path.trim());
+    }
+    if (typeof payload?.session_id === 'string' && payload.session_id.trim()) {
+      args.push('--session-id', payload.session_id.trim());
+    }
+    for (const ref of [...localMatches, ...urlMatches]) {
+      args.push('--ref', ref);
+    }
+    try {
+      const out = execFileSync('node', args, {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        timeout: 6000,
+      });
+      const parsed = JSON.parse(out);
+      const images = Array.isArray(parsed?.images) ? parsed.images : [];
+      // Ref markers carry a `source`; pasted ones do not. Counting this way stays correct
+      // when a named path does not exist on disk and the extractor drops it.
+      markedPasted = images.filter((img) => !img?.source).length;
+      markedPath = images.filter((img) => img?.source === 'path').length;
+      markedUrl = images.filter((img) => img?.source === 'url').length;
+    } catch (err) {
+      process.stderr.write(`vision-router: extractor call skipped (${err?.message ?? err})\n`);
+    }
+  }
+
+  // `cases` reflects what the PROMPT mentioned; `armed` reflects what actually got a
+  // pending marker. They differ when a named path does not resolve from the project root
+  // — still worth a hint, but the gate is not armed and must not be claimed to be.
+  const cases = [];
+  if (markedPasted > 0) cases.push('pasted image');
+  if (localMatches.length > 0) cases.push('local file path');
+  if (urlMatches.length > 0) cases.push('image URL');
+  const armed = markedPasted + markedPath + markedUrl;
+
+  if (cases.length === 0) {
+    process.exit(0);
+    return;
+  }
+
+  // Optional: name the concrete vision model when the UNIC gateway is active
+  // (TASK-003). Never fatal — a missing/broken gateway module just omits the note.
+  let unicNote = '';
+  try {
+    const gatewayPath = path.join(projectRoot, '.claude', 'ukit', 'index', 'unic-gateway.mjs');
+    if (fs.existsSync(gatewayPath)) {
+      const mod = await import(pathToFileURL(gatewayPath).href);
+      if (typeof mod.detectUnicGateway === 'function') {
+        const result = mod.detectUnicGateway({ rootDir: projectRoot });
+        if (result?.unicMode) {
+          unicNote = `  (UNIC gateway active — ${result.visionModel} routes through it.)`;
+        }
+      }
+    }
+  } catch {
+    unicNote = '';
+  }
+
+  const lines = [
+    `UKIT VISION ROUTE — image input detected (${cases.join(', ')}).`,
+    armed > 0
+      ? 'unic-code / unic-smart cannot read images on this gateway, and Edit/Write is now GATED\nuntil a vision analysis exists. Do this before anything else:'
+      : 'unic-code / unic-smart cannot read images on this gateway. Do this before anything else:',
+    '  1. node .claude/ukit/index/extract-image.mjs --json',
+    '  2. Agent(subagent_type: "ukit-vision-analyst")  [model: unic-vision]',
+    '     Pass the ABSOLUTE paths from images[].path as text — a subagent does NOT',
+    '     inherit image blocks; it can only Read files.',
+    '  3. Continue the real task using the returned description.',
+  ];
+  if (markedUrl > 0) {
+    lines.push('  Image URL detected: ukit-vision-analyst downloads it with Bash into');
+    lines.push('  .ukit/storage/cache/vision/, then Reads the downloaded file.');
+  }
+  if (localMatches.length > markedPath) {
+    lines.push('  A named image path did not resolve from the project root — resolve it before');
+    lines.push('  analysing, and do not guess at its contents.');
+  }
+  if (unicNote) lines.push(unicNote);
+
+  process.stdout.write(`${lines.join('\n')}\n`);
+  process.exit(0);
+})().catch((err) => {
+  process.stderr.write(`vision-router: unexpected error (${err?.message ?? err})\n`);
+  process.exit(0);
+});
+NODE
+
+exit 0

package/templates/.claude/settings.json

@@ -82,6 +82,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-model-guard.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-gate.sh\"",
+            "timeout": 8
           }
         ]
       },
@@ -145,6 +150,11 @@
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-router.sh\"",
             "timeout": 8
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/vision-router.sh\"",
+            "timeout": 8
           }
         ]
       }

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

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+/**
+ * extract-image.mjs — materialise transcript images so a subagent can Read them.
+ *
+ * A spawned subagent receives TEXT ONLY and does not inherit the parent's image
+ * blocks, so pasted images are invisible unless this script first decodes them
+ * to disk. This is the single home of the sha256 key: `pending-<sha>` markers
+ * (written by --mark-pending) and `<sha>.<ext>` image files (written by a normal
+ * extract) MUST agree exactly, or the TASK-008 gate deadlocks forever. Both
+ * paths call the same hashPayload() function on the exact base64 string as it
+ * appears in the transcript — no trimming, no normalising, no decoding first.
+ *
+ * Usage:
+ *   node extract-image.mjs [options]
+ *     --session <path>   explicit transcript .jsonl (default: auto-discover)
+ *     --detect           count only; decode nothing, write nothing
+ *     --mark-pending     write pending-<sha>.json markers; NO decode, NO image write
+ *     --json             machine-readable stdout
+ *     --limit <n>        max images, default 3 (most recent first)
+ *     --out <dir>        default <projectRoot>/.ukit/storage/cache/vision
+ *     --session-id <id>  marker subdirectory (default: from transcript filename, else "default")
+ *     --ref <path|url>   repeatable; arm a marker for an image named in the prompt text
+ *                        rather than pasted. Pasted images hash their base64 payload;
+ *                        a local file hashes its bytes and a URL hashes the URL string.
+ *                        Different domains, but the sha only has to be stable and unique.
+ *
+ * Builtins only (fs, path, crypto, os). No dependencies, no network calls.
+ * Never throws: always exits 0, including "no images found" and missing session file.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const MEDIA_EXT = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/gif': 'gif',
+  'image/webp': 'webp',
+};
+
+const DEFAULT_LIMIT = 3;
+const MAX_DECODED_BYTES = 10 * 1024 * 1024; // 10 MB
+const RETENTION_MAX_IMAGE_FILES = 20;
+const MARKER_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24h
+
+/**
+ * Single shared hash function for both the image filename sha and the
+ * pending-<sha> marker sha. Hashes the base64 payload string EXACTLY as it
+ * appears in the transcript (no trim/normalise/decode) so the two paths can
+ * never diverge.
+ */
+export function hashPayload(base64Data) {
+  return crypto.createHash('sha256').update(base64Data, 'utf8').digest('hex');
+}
+
+const REF_EXT_RE = /\.(png|jpe?g|gif|webp|bmp)(?:[?#].*)?$/i;
+const EXT_MEDIA = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  bmp: 'image/bmp',
+};
+
+/**
+ * Turns --ref values (local paths and URLs named in the prompt) into markers.
+ *
+ * Pasted images hash their base64 payload; these have no payload to hash, so a local
+ * file hashes its bytes and a URL hashes the URL string. The domains differ, but the
+ * sha only has to be stable and unique — the gate matches pending-<sha> to
+ * analyzed-<sha> by filename and never recomputes it. Still routed through
+ * crypto.createHash here so this file remains the single owner of the hash.
+ *
+ * Silently drops anything that is not an image ref or cannot be read: this feeds a
+ * hook that must never wedge a prompt.
+ */
+export function resolveRefs(values) {
+  const out = [];
+  const seen = new Set();
+  for (const value of values ?? []) {
+    const match = REF_EXT_RE.exec(value);
+    if (!match) continue;
+    const mediaType = EXT_MEDIA[match[1].toLowerCase()] ?? 'application/octet-stream';
+    const isUrl = /^https?:\/\//i.test(value);
+    let sha;
+    if (isUrl) {
+      sha = crypto.createHash('sha256').update(value, 'utf8').digest('hex');
+    } else {
+      let bytes;
+      try {
+        bytes = fs.readFileSync(path.resolve(value));
+      } catch {
+        continue; // path named in the prompt but not present on disk: nothing to analyse
+      }
+      if (bytes.length > MAX_DECODED_BYTES) continue;
+      sha = crypto.createHash('sha256').update(bytes).digest('hex');
+    }
+    if (seen.has(sha)) continue;
+    seen.add(sha);
+    out.push({ sha, mediaType, source: isUrl ? 'url' : 'path', value });
+  }
+  return out;
+}
+
+function parseArgs(argv) {
+  const opts = {
+    session: null,
+    detect: false,
+    markPending: false,
+    json: false,
+    limit: DEFAULT_LIMIT,
+    out: null,
+    sessionId: null,
+    refs: [],
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--session') {
+      opts.session = argv[i + 1];
+      i += 1;
+    } else if (arg === '--detect') {
+      opts.detect = true;
+    } else if (arg === '--mark-pending') {
+      opts.markPending = true;
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--limit') {
+      const n = Number(argv[i + 1]);
+      if (Number.isFinite(n) && n > 0) opts.limit = Math.floor(n);
+      i += 1;
+    } else if (arg === '--out') {
+      opts.out = argv[i + 1];
+      i += 1;
+    } else if (arg === '--session-id') {
+      opts.sessionId = argv[i + 1];
+      i += 1;
+    } else if (arg === '--ref') {
+      const value = argv[i + 1];
+      if (typeof value === 'string' && value.trim()) opts.refs.push(value.trim());
+      i += 1;
+    }
+  }
+  return opts;
+}
+
+function slugifyCwd(cwd) {
+  return cwd.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+function discoverSessionFile(cwd) {
+  const slug = slugifyCwd(cwd);
+  const dir = path.join(os.homedir(), '.claude', 'projects', slug);
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  let newestPath = null;
+  let newestMtimeMs = -Infinity;
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue;
+    const full = path.join(dir, entry.name);
+    let stat;
+    try {
+      stat = fs.statSync(full);
+    } catch {
+      continue;
+    }
+    if (stat.mtimeMs > newestMtimeMs) {
+      newestMtimeMs = stat.mtimeMs;
+      newestPath = full;
+    }
+  }
+  return newestPath;
+}
+
+function readLines(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+  return raw.split('\n').filter((line) => line.trim().length > 0);
+}
+
+/**
+ * Parses each JSONL line independently. A malformed line is skipped via its
+ * own try/catch and never throws out to the caller.
+ */
+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 });
+      }
+    } catch {
+      // malformed line: skip and continue
+    }
+  }
+  return blocks;
+}
+
+/**
+ * Filters to the allowlisted media types, dedupes by sha (content-addressed —
+ * same payload always produces the same key), and orders most-recent-first.
+ */
+function selectImages(blocks, limit) {
+  const allowed = blocks.filter((b) => MEDIA_EXT[b.mediaType]);
+  const bySha = new Map();
+  for (const block of allowed) {
+    const sha = hashPayload(block.data);
+    bySha.set(sha, { sha, mediaType: block.mediaType, data: block.data, lineIndex: block.lineIndex });
+  }
+  const deduped = Array.from(bySha.values());
+  deduped.sort((a, b) => b.lineIndex - a.lineIndex);
+  return deduped.slice(0, limit);
+}
+
+function pruneImageFiles(outDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(outDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const imageFiles = entries
+    .filter((e) => e.isFile() && /^[0-9a-f]{64}\.(png|jpg|gif|webp)$/.test(e.name))
+    .map((e) => {
+      const full = path.join(outDir, e.name);
+      let mtimeMs = 0;
+      try {
+        mtimeMs = fs.statSync(full).mtimeMs;
+      } catch {
+        // ignore
+      }
+      return { full, mtimeMs };
+    })
+    .sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  for (const f of imageFiles.slice(RETENTION_MAX_IMAGE_FILES)) {
+    try {
+      fs.unlinkSync(f.full);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+function pruneMarkerDirs(outDir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(outDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const full = path.join(outDir, entry.name);
+    let mtimeMs;
+    try {
+      mtimeMs = fs.statSync(full).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (now - mtimeMs > MARKER_MAX_AGE_MS) {
+      try {
+        fs.rmSync(full, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+function printResult(opts, result) {
+  if (opts.json) {
+    console.log(JSON.stringify(result));
+    return;
+  }
+  console.log(`imageCount: ${result.imageCount}`);
+  for (const img of result.images) {
+    if (img.path) console.log(img.path);
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const cwd = process.cwd();
+
+  const sessionPath = opts.session ? path.resolve(opts.session) : discoverSessionFile(cwd);
+  const outDir = opts.out
+    ? path.resolve(opts.out)
+    : path.join(cwd, '.ukit', 'storage', 'cache', 'vision');
+
+  const sessionId = opts.sessionId
+    || (sessionPath ? path.basename(sessionPath, path.extname(sessionPath)) : 'default');
+
+  const lines = sessionPath ? readLines(sessionPath) : [];
+  const blocks = extractImageBlocks(lines);
+  const selected = selectImages(blocks, opts.limit);
+  const refs = resolveRefs(opts.refs);
+
+  // --detect is report-only, so it must not short-circuit --mark-pending when both are
+  // passed together. vision-router.sh combines them; short-circuiting here would arm
+  // nothing and leave the TASK-008 write gate permanently open.
+  if (opts.detect && !opts.markPending) {
+    printResult(opts, { imageCount: selected.length + refs.length, sessionId, images: [] });
+    return;
+  }
+
+  if (opts.markPending) {
+    const markerDir = path.join(outDir, sessionId);
+    if (selected.length > 0 || refs.length > 0) {
+      try {
+        fs.mkdirSync(markerDir, { recursive: true });
+      } catch (err) {
+        process.stderr.write(`extract-image: failed to create marker dir ${markerDir}: ${err.message}\n`);
+        printResult(opts, { imageCount: 0, sessionId, images: [] });
+        return;
+      }
+    }
+
+    const written = [];
+    for (const img of selected) {
+      const markerPath = path.join(markerDir, `pending-${img.sha}.json`);
+      const marker = { sha: img.sha, mediaType: img.mediaType, ts: Date.now(), sessionId };
+      try {
+        fs.writeFileSync(markerPath, JSON.stringify(marker));
+        written.push({ sha: img.sha, path: markerPath, mediaType: img.mediaType, bytes: 0 });
+      } catch (err) {
+        process.stderr.write(`extract-image: failed to write marker ${markerPath}: ${err.message}\n`);
+      }
+    }
+    for (const ref of refs) {
+      const markerPath = path.join(markerDir, `pending-${ref.sha}.json`);
+      const marker = {
+        sha: ref.sha,
+        mediaType: ref.mediaType,
+        ts: Date.now(),
+        sessionId,
+        source: ref.source,
+        ref: ref.value,
+      };
+      try {
+        fs.writeFileSync(markerPath, JSON.stringify(marker));
+        written.push({ sha: ref.sha, path: markerPath, mediaType: ref.mediaType, bytes: 0, source: ref.source, ref: ref.value });
+      } catch (err) {
+        process.stderr.write(`extract-image: failed to write marker ${markerPath}: ${err.message}\n`);
+      }
+    }
+    pruneMarkerDirs(outDir);
+    printResult(opts, { imageCount: written.length, sessionId, images: written });
+    return;
+  }
+
+  // default: decode + write image files
+  if (selected.length > 0) {
+    try {
+      fs.mkdirSync(outDir, { recursive: true });
+    } catch (err) {
+      process.stderr.write(`extract-image: failed to create out dir ${outDir}: ${err.message}\n`);
+      printResult(opts, { imageCount: 0, sessionId, images: [] });
+      return;
+    }
+  }
+
+  const images = [];
+  for (const img of selected) {
+    let decoded;
+    try {
+      decoded = Buffer.from(img.data, 'base64');
+    } catch (err) {
+      process.stderr.write(`extract-image: failed to decode image (sha=${img.sha}): ${err.message}\n`);
+      continue;
+    }
+    if (decoded.length > MAX_DECODED_BYTES) {
+      process.stderr.write(
+        `extract-image: skipping oversized image (sha=${img.sha}, bytes=${decoded.length} > ${MAX_DECODED_BYTES})\n`
+      );
+      continue;
+    }
+    const ext = MEDIA_EXT[img.mediaType];
+    const filePath = path.join(outDir, `${img.sha}.${ext}`);
+    try {
+      fs.writeFileSync(filePath, decoded);
+    } catch (err) {
+      process.stderr.write(`extract-image: failed to write ${filePath}: ${err.message}\n`);
+      continue;
+    }
+    images.push({ sha: img.sha, path: filePath, mediaType: img.mediaType, bytes: decoded.length });
+  }
+  pruneImageFiles(outDir);
+  printResult(opts, { imageCount: images.length, sessionId, images });
+}
+
+// Only run as a CLI. Importing this module (tests import resolveRefs/hashPayload) must
+// not decode images, write markers, or prune the real cache as a side effect.
+const invokedDirectly = (() => {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return fs.realpathSync(entry) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+if (invokedDirectly) {
+  try {
+    main();
+    process.exitCode = 0;
+  } catch (err) {
+    process.stderr.write(`extract-image: unexpected error: ${err?.message ?? err}\n`);
+    process.exitCode = 0;
+  }
+}