@ngockhoale/ukit 1.6.4 → 1.6.5

package/templates/.claude/ukit/index/route-task.mjs

@@ -2,6 +2,8 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import * as indexCore from './lib/index-core.mjs';
 import {
   DEFAULT_RECENT_CACHE_MAX_ENTRIES,
@@ -9,6 +11,7 @@ import {
   writeRecentCacheEntry,
 } from './cache-utils.mjs';
 import { ROUTE_CATALOG } from './route-catalog.mjs';
+import { detectUnicGateway } from './unic-gateway.mjs';
 
 const {
   resolveContext,
@@ -44,6 +47,119 @@ const buildNormalizedRouteSignalText = typeof indexCore.buildRouteSignalText ===
       .join('\n')
       .toLowerCase();
 
+// --- Vision lane (TASK-007) ---------------------------------------------------
+// Vision is a CAPABILITY lane, orthogonal to the lite/code/smart COST tier. It is emitted as
+// separate `visionLane`/`visionModel`/`visionReason` fields alongside `modelTier`, never in place
+// of it. `modelTier` must never take the value `vision` (see buildExecutionContract() below).
+const __routeTaskDir = path.dirname(fileURLToPath(import.meta.url));
+const EXTRACT_IMAGE_SCRIPT_PATH = path.join(__routeTaskDir, 'extract-image.mjs');
+const VISION_DETECT_TIMEOUT_MS = 800;
+const VISION_IMAGE_URL_RE = /https?:\/\/\S*\.(?:png|jpe?g|gif|webp|bmp)\b/i;
+const VISION_IMAGE_PATH_RE = /\.(?:png|jpe?g|gif|webp|bmp)\b/i;
+
+/**
+ * Cheap, synchronous, anchored detection against real file extensions / image URLs only.
+ * Deliberately does NOT match loose substrings like "imagine", "imagery", or "anh" — those
+ * contain image-ish text but never a literal `.png`/`.jpg`/etc extension.
+ */
+function detectVisionReasonFromText(text = '') {
+  const value = String(text || '');
+  if (!value) return null;
+  if (VISION_IMAGE_URL_RE.test(value)) return 'url-in-text';
+  if (VISION_IMAGE_PATH_RE.test(value)) return 'path-in-text';
+  return null;
+}
+
+/**
+ * Best-effort probe for a pasted image in the current session transcript, via extract-image.mjs
+ * --detect. Never throws, never blocks the hot path beyond a short timeout: any spawn failure,
+ * non-zero exit, timeout, or malformed JSON degrades to "no image detected".
+ */
+function detectPastedImageViaExtractor({ rootDir = process.cwd() } = {}) {
+  try {
+    const result = spawnSync(process.execPath, [EXTRACT_IMAGE_SCRIPT_PATH, '--detect', '--json'], {
+      cwd: rootDir,
+      encoding: 'utf8',
+      timeout: VISION_DETECT_TIMEOUT_MS,
+    });
+    if (!result || result.error || result.status !== 0 || !result.stdout) {
+      return false;
+    }
+    const parsed = JSON.parse(result.stdout);
+    return Number(parsed?.imageCount) > 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Gateway-aware model pick (TASK-003 aware). Calls detectUnicGateway() directly (not the CLI) to
+ * avoid a spawn on the hot path. unicMode true -> unic-vision. unicMode false -> read
+ * orchestration.modelTiers.vision.fallbackModel from config (TASK-001). Neither available -> omit
+ * visionModel and return an advisory; a blind model is never silently named.
+ */
+async function resolveVisionModel({ rootDir = process.cwd() } = {}) {
+  let gateway = null;
+  try {
+    gateway = detectUnicGateway({ rootDir });
+  } catch {
+    gateway = null;
+  }
+
+  if (gateway?.unicMode) {
+    return { visionModel: gateway.visionModel || 'unic-vision', visionAdvisory: null };
+  }
+
+  const config = await readJson(path.join(rootDir, '.ukit', 'storage', 'config.json'), null);
+  const fallbackModel = config?.orchestration?.modelTiers?.vision?.fallbackModel;
+  if (typeof fallbackModel === 'string' && fallbackModel.trim()) {
+    return { visionModel: fallbackModel.trim(), visionAdvisory: null };
+  }
+
+  return {
+    visionModel: null,
+    visionAdvisory: 'vision lane detected but no vision model is configured (UNIC gateway inactive '
+      + 'and orchestration.modelTiers.vision.fallbackModel is missing); no model was named to avoid '
+      + 'silently naming a blind model.',
+  };
+}
+
+/**
+ * Detects the vision lane and, when applicable, resolves the model to use for it. Returns null
+ * when the task has no image signal at all (silent when not applicable — no visionLane line, and
+ * the (costlier) extractor probe only runs when the cheap flag/text checks found nothing).
+ */
+async function resolveVisionLane({
+  rootDir = process.cwd(),
+  promptText = '',
+  commandText = '',
+  targetFile = '',
+  visionFlag = false,
+} = {}) {
+  let visionReason = visionFlag ? 'explicit-flag' : null;
+
+  if (!visionReason) {
+    const haystack = [promptText, commandText, targetFile].filter(Boolean).join('\n');
+    visionReason = detectVisionReasonFromText(haystack);
+  }
+
+  if (!visionReason && detectPastedImageViaExtractor({ rootDir })) {
+    visionReason = 'pasted-image';
+  }
+
+  if (!visionReason) {
+    return null;
+  }
+
+  const { visionModel, visionAdvisory } = await resolveVisionModel({ rootDir });
+  return {
+    visionLane: true,
+    visionReason,
+    visionModel,
+    visionAdvisory,
+  };
+}
+
 async function main() {
   const args = process.argv.slice(2);
   const rootDir = getRootDir(args);
@@ -51,9 +167,11 @@ async function main() {
   const routeCachePath = path.join(rootDir, '.claude', 'ukit', 'route-cache.json');
   const routeAuditPath = path.join(rootDir, '.ukit', 'storage', 'cache', 'route-audit.json');
   const previousState = await readJson(sharedStatePath, {});
+  const escalationConfig = await readJson(path.join(rootDir, '.ukit', 'storage', 'config.json'), null);
   const targetFile = readFlagValue(args, '--target');
   const taskType = readFlagValue(args, '--type');
   const commandText = readFlagValue(args, '--tool-command') ?? '';
+  const visionFlag = args.includes('--vision');
   const lastPrompt = readFlagValue(args, '--last-prompt')
     ?? previousState?.routingContext?.lastExplicitUserPromptText
     ?? '';
@@ -81,6 +199,7 @@ async function main() {
     adapter,
     lastExplicitUserPromptText: lastPrompt,
     commandNamespace,
+    visionFlag,
   });
   const useIndexedContext = shouldUseIndexedContext({
     activeSkills: preparedRoute.activeSkills,
@@ -145,11 +264,16 @@ async function main() {
           continuationState: advanceContinuationState(
             cachedRouteState.routeSummary.continuationState ?? null,
             cachedRouteState.routeSummary.continuationState ?? null,
+            resolveEscalationSettings(escalationConfig),
           ),
         }
       : null;
     if (rescuedRouteSummary) {
       applyRescueBiasToRouteSummary(rescuedRouteSummary);
+      applyEscalationToRouteSummary(rescuedRouteSummary, {
+        config: escalationConfig,
+        targetFile: cachedRouteState.routingContext?.targetFile ?? null,
+      });
     }
     const sharedState = {
       ...cachedRouteState,
@@ -185,6 +309,7 @@ async function main() {
     previousContextSnapshot,
     recentOutputSnapshot,
     previousRouteSummary: previousState?.routeSummary ?? null,
+    escalationConfig,
   });
   await seedHelperCaches({
     rootDir,
@@ -248,6 +373,7 @@ async function prepareTaskRoute({
   taskType = null,
   adapter = 'claude',
   lastExplicitUserPromptText = '',
+  visionFlag = false,
 } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const normalizedPrompt = String(promptText || '').trim();
@@ -301,6 +427,13 @@ async function prepareTaskRoute({
     executionCandidates,
   });
   const preservedPrompt = normalizedPrompt || String(lastExplicitUserPromptText || '').trim();
+  const visionInfo = await resolveVisionLane({
+    rootDir: absoluteRoot,
+    promptText: normalizedPrompt,
+    commandText: normalizedCommand,
+    targetFile: normalizedTarget,
+    visionFlag: Boolean(visionFlag),
+  });
 
   return {
     rootDir: absoluteRoot,
@@ -317,6 +450,10 @@ async function prepareTaskRoute({
       executionScores,
       executionCandidates,
       executionMode,
+      visionLane: Boolean(visionInfo?.visionLane),
+      visionReason: visionInfo?.visionReason ?? null,
+      visionModel: visionInfo?.visionModel ?? null,
+      visionAdvisory: visionInfo?.visionAdvisory ?? null,
     },
   };
 }
@@ -332,6 +469,7 @@ async function finalizeTaskRoute({
   previousContextSnapshot = null,
   recentOutputSnapshot = null,
   previousRouteSummary = null,
+  escalationConfig = null,
 } = {}) {
   const absoluteRoot = path.resolve(rootDir);
   const activeSkills = preparedRoute?.activeSkills ?? [];
@@ -399,8 +537,13 @@ async function finalizeTaskRoute({
   routeSummary.continuationState = advanceContinuationState(
     routeSummary.continuationState,
     previousRouteSummary?.continuationState ?? null,
+    resolveEscalationSettings(escalationConfig),
   );
   applyRescueBiasToRouteSummary(routeSummary);
+  applyEscalationToRouteSummary(routeSummary, {
+    config: escalationConfig,
+    targetFile: routingContext.targetFile ?? null,
+  });
   const approachSelector = routeSummary?.approachSelector ?? null;
 
   return {
@@ -436,6 +579,24 @@ function printRouteState(state) {
   if (state.routeSummary?.executionContract?.modelTier) {
     console.log(`modelTier: ${state.routeSummary.executionContract.modelTier}`);
   }
+  if (state.routeSummary?.escalatedTier) {
+    console.log(`escalatedTier: ${state.routeSummary.escalatedTier}`);
+    if (state.routeSummary.escalationReason) {
+      console.log(`escalationReason: ${state.routeSummary.escalationReason}`);
+    }
+  }
+  if (state.routeSummary?.visionLane) {
+    console.log(`visionLane: ${state.routeSummary.visionLane}`);
+    if (state.routeSummary.visionModel) {
+      console.log(`visionModel: ${state.routeSummary.visionModel}`);
+    }
+    if (state.routeSummary.visionReason) {
+      console.log(`visionReason: ${state.routeSummary.visionReason}`);
+    }
+    if (state.routeSummary.visionAdvisory) {
+      console.log(`visionAdvisory: ${state.routeSummary.visionAdvisory}`);
+    }
+  }
   if (nextDisplay) {
     console.log(`next: ${nextDisplay}`);
   }
@@ -1355,6 +1516,7 @@ function buildRouteSummary({
   );
   const nextActionCommand = compactHelperLane ? null : nextAction?.command ?? null;
   const handoffFile = routingContext.intentMode === 'handoff' ? 'docs/AI_HANDOFF/ACTIVE.md' : null;
+  const visionLane = Boolean(routingContext.visionLane);
   const line = [
     routingContext.taskType ? `task=${routingContext.taskType}` : null,
     handoffFile ? `handoff=${handoffFile}` : null,
@@ -1386,6 +1548,12 @@ function buildRouteSummary({
     nextActionCommand,
     helperHint,
     contextMode,
+    ...(visionLane ? {
+      visionLane: true,
+      visionReason: routingContext.visionReason ?? null,
+      ...(routingContext.visionModel ? { visionModel: routingContext.visionModel } : {}),
+      ...(routingContext.visionAdvisory ? { visionAdvisory: routingContext.visionAdvisory } : {}),
+    } : {}),
     line: line || 'task=unknown',
   };
 }
@@ -1876,11 +2044,114 @@ function buildContinuationState({
   };
 }
 
-function advanceContinuationState(continuationState = null, previousContinuationState = null) {
+// --- Escalation (TASK-009) ------------------------------------------------------------------
+// Consumes the repeatCount/rescueMode signal `advanceContinuationState` already computes and
+// exposes it to model-tier selection. Escalation is a COST ladder (lite -> code -> smart),
+// orthogonal to the vision capability lane (TASK-007): 'vision' must never appear in tierOrder
+// and escalatedTier must never take the value 'vision'. Thresholds are read from
+// orchestration.escalation (TASK-001); when config is absent or malformed, every threshold falls
+// back to the literal `2` / `3` that shipped before this change, so an unconfigured project sees
+// byte-identical behaviour.
+const DEFAULT_ESCALATION_DEBUG_LOOP_THRESHOLD = 2;
+const DEFAULT_ESCALATION_STUCK_RISK_THRESHOLD = 3;
+const DEFAULT_ESCALATION_TIER_ORDER = ['lite', 'code', 'smart'];
+const DEFAULT_ESCALATION_CAP = 'smart';
+
+function resolveEscalationSettings(config = null) {
+  const raw = config?.orchestration?.escalation;
+  const enabled = typeof raw?.enabled === 'boolean' ? raw.enabled : true;
+  const debugLoopThreshold = Number.isFinite(raw?.debugLoopThreshold) && raw.debugLoopThreshold > 0
+    ? raw.debugLoopThreshold
+    : DEFAULT_ESCALATION_DEBUG_LOOP_THRESHOLD;
+  const stuckRiskThreshold = Number.isFinite(raw?.stuckRiskThreshold) && raw.stuckRiskThreshold > 0
+    ? raw.stuckRiskThreshold
+    : DEFAULT_ESCALATION_STUCK_RISK_THRESHOLD;
+  const tierOrderCandidate = Array.isArray(raw?.tierOrder) && raw.tierOrder.length > 0
+    && raw.tierOrder.every((tier) => typeof tier === 'string' && tier.trim())
+    ? raw.tierOrder
+    : DEFAULT_ESCALATION_TIER_ORDER;
+  // 'vision' is a capability lane, never a cost rung — never let it into the escalation ladder.
+  const tierOrder = tierOrderCandidate.includes('vision')
+    ? DEFAULT_ESCALATION_TIER_ORDER
+    : tierOrderCandidate;
+  const cap = typeof raw?.cap === 'string' && tierOrder.includes(raw.cap)
+    ? raw.cap
+    : (tierOrder.includes(DEFAULT_ESCALATION_CAP) ? DEFAULT_ESCALATION_CAP : tierOrder[tierOrder.length - 1]);
+
+  return {
+    enabled, debugLoopThreshold, stuckRiskThreshold, tierOrder, cap,
+  };
+}
+
+/**
+ * Escalates exactly one rung above `modelTier` on `tierOrder`, capped at `cap`. Returns null when
+ * escalation is disabled, `repeatCount` hasn't reached `debugLoopThreshold`, or `modelTier` isn't
+ * on the cost ladder (e.g. no contract selected). Never returns 'vision'.
+ */
+function computeEscalation({
+  modelTier = null,
+  repeatCount = null,
+  config = null,
+  targetFile = null,
+} = {}) {
+  if (!modelTier || !Number.isFinite(repeatCount)) {
+    return null;
+  }
+  const settings = resolveEscalationSettings(config);
+  if (!settings.enabled || repeatCount < settings.debugLoopThreshold) {
+    return null;
+  }
+  const currentIndex = settings.tierOrder.indexOf(modelTier);
+  if (currentIndex === -1) {
+    return null;
+  }
+  const capIndex = settings.tierOrder.indexOf(settings.cap);
+  const effectiveCapIndex = capIndex === -1 ? settings.tierOrder.length - 1 : capIndex;
+  const escalatedIndex = Math.min(currentIndex + 1, effectiveCapIndex);
+  const escalatedTier = settings.tierOrder[escalatedIndex];
+
+  return {
+    escalatedTier,
+    escalationReason: `repeat-count=${repeatCount} threshold=${settings.debugLoopThreshold} file=${targetFile ?? 'null'}`,
+  };
+}
+
+/** Attaches escalatedTier/escalationReason to routeSummary, additive alongside modelTier. */
+function applyEscalationToRouteSummary(routeSummary = null, { config = null, targetFile = null } = {}) {
+  if (!routeSummary || typeof routeSummary !== 'object') {
+    return routeSummary;
+  }
+
+  const escalation = computeEscalation({
+    modelTier: routeSummary.executionContract?.modelTier ?? null,
+    repeatCount: routeSummary.continuationState?.repeatCount ?? null,
+    config,
+    targetFile,
+  });
+
+  if (escalation) {
+    routeSummary.escalatedTier = escalation.escalatedTier;
+    routeSummary.escalationReason = escalation.escalationReason;
+  } else {
+    delete routeSummary.escalatedTier;
+    delete routeSummary.escalationReason;
+  }
+
+  return routeSummary;
+}
+
+function advanceContinuationState(continuationState = null, previousContinuationState = null, thresholds = null) {
   if (!continuationState || typeof continuationState !== 'object') {
     return continuationState;
   }
 
+  const debugLoopThreshold = Number.isFinite(thresholds?.debugLoopThreshold)
+    ? thresholds.debugLoopThreshold
+    : DEFAULT_ESCALATION_DEBUG_LOOP_THRESHOLD;
+  const stuckRiskThreshold = Number.isFinite(thresholds?.stuckRiskThreshold)
+    ? thresholds.stuckRiskThreshold
+    : DEFAULT_ESCALATION_STUCK_RISK_THRESHOLD;
+
   if (!continuationState.required) {
     return {
       ...continuationState,
@@ -1903,7 +2174,7 @@ function advanceContinuationState(continuationState = null, previousContinuation
   const repeatCount = sameMilestone
     ? Math.max(1, Number(previousContinuationState?.repeatCount ?? 1) + 1)
     : 1;
-  const rescueMode = repeatCount >= 2
+  const rescueMode = repeatCount >= debugLoopThreshold
     ? (
       currentReasons.includes('pending-bounded-context')
         ? 'finish-current-milestone-before-more-reading'
@@ -1914,14 +2185,14 @@ function advanceContinuationState(continuationState = null, previousContinuation
         )
     )
     : null;
-  const stuckRisk = repeatCount >= 3
+  const stuckRisk = repeatCount >= stuckRiskThreshold
     ? 'high'
-    : (repeatCount === 2 ? 'elevated' : null);
-  const wideningBlocked = repeatCount >= 2 && Boolean(rescueMode);
-  const nextMilestone = repeatCount >= 2 && currentReasons.includes('missing-write-evidence')
+    : (repeatCount === debugLoopThreshold ? 'elevated' : null);
+  const wideningBlocked = repeatCount >= debugLoopThreshold && Boolean(rescueMode);
+  const nextMilestone = repeatCount >= debugLoopThreshold && currentReasons.includes('missing-write-evidence')
     ? 'finish-write-before-more-analysis'
     : (
-      repeatCount >= 2 && currentReasons.includes('pending-bounded-context')
+      repeatCount >= debugLoopThreshold && currentReasons.includes('pending-bounded-context')
         ? 'finish-current-milestone-before-more-reading'
         : continuationState.nextMilestone
     );
@@ -2376,6 +2647,8 @@ function buildRouteRequestKey({
     contextIntent: routingContext.contextIntent ?? '',
     taskType: routingContext.taskType ?? '',
     executionMode: routingContext.executionMode ?? '',
+    visionLane: Boolean(routingContext.visionLane),
+    visionReason: routingContext.visionReason ?? '',
   });
 }
 
@@ -2559,6 +2832,16 @@ function compactRouteSummary(routeSummary = null) {
     nextActionType: routeSummary.nextActionType ?? null,
     nextActionCommand: routeSummary.nextActionCommand ?? null,
     helperHint: routeSummary.helperHint ?? null,
+    ...(routeSummary.escalatedTier ? {
+      escalatedTier: routeSummary.escalatedTier,
+      escalationReason: routeSummary.escalationReason ?? null,
+    } : {}),
+    ...(routeSummary.visionLane ? {
+      visionLane: true,
+      visionReason: routeSummary.visionReason ?? null,
+      ...(routeSummary.visionModel ? { visionModel: routeSummary.visionModel } : {}),
+      ...(routeSummary.visionAdvisory ? { visionAdvisory: routeSummary.visionAdvisory } : {}),
+    } : {}),
   };
 }