@ngockhoale/ukit 1.6.4 → 1.6.6

package/templates/.claude/ukit/index/unic-gateway.mjs

@@ -0,0 +1,271 @@
+#!/usr/bin/env node
+/**
+ * unic-gateway.mjs (TASK-003)
+ *
+ * Detects whether any locally configured AI tool (Claude Code, Codex, or Kilo Code) is pointed at
+ * the UNIC gateway — i.e. its base URL contains "unicjsc.com". Per the user's rule, a hit in ANY
+ * tool activates UNIC routing (`unicMode: true`), so the vision lane can pin `unic-vision` when it
+ * is available in the Codex model catalog, and fall back safely when it is not.
+ *
+ * Self-contained: reads only env vars and local files. Does NOT read `.ukit/storage/config.json`,
+ * so it has no dependency on TASK-001 and stays usable in Wave 1.
+ *
+ * Probe order (first hit sets `source`; every hit is recorded in `sources`):
+ *   1. process.env.ANTHROPIC_BASE_URL           -> 'env'
+ *   2. process.env.OPENAI_BASE_URL              -> 'env'
+ *   3. project .claude/settings.json -> env     -> 'claude-settings'
+ *   4. ~/.claude/settings.json -> env            -> 'claude-settings'
+ *   5. project .codex/config.toml                -> 'codex'
+ *   6. ~/.codex/config.toml                       -> 'codex'
+ *   7. ~/.kilocode/secrets.json (presence only)   -> 'kilo'
+ *
+ * SECURITY (non-negotiable): `~/.kilocode/secrets.json` is a real secrets file. This module only
+ * ever tests it for substring presence of "unicjsc.com", then lets the buffer fall out of scope.
+ * It never logs, returns, echoes, or otherwise embeds that file's contents anywhere — including in
+ * error messages. Nothing derived from that file may appear in this module's output beyond the
+ * literal source label "kilo".
+ *
+ * TOML (deliberate trade-off): no TOML parser dependency is added — repo `dependencies` is
+ * `{"yaml":"^2.8.2"}` only, and adding a parser for one `base_url` line fails Simplicity First.
+ * Codex config.toml is scanned with a narrow anchored regex that looks for a `base_url = "..."`
+ * assignment containing "unicjsc.com" on a single line. It does not attempt real TOML parsing, so
+ * exotic quoting/escaping (multi-line strings, unusual escapes) will not match. That degrades to
+ * "no hit" (`unicMode: false`), which fails safe rather than throwing or false-negatively passing.
+ *
+ * Contract: this module must NEVER throw and must NEVER exit non-zero, in any case (missing files,
+ * malformed JSON/TOML, unreadable paths, etc. all degrade to a clean "no hit").
+ *
+ * Test overrides: pass { rootDir, homeDir } directly to detectUnicGateway(), or set the env vars
+ * UKIT_TEST_ROOT / UKIT_TEST_HOME (used only when explicit options are not supplied) so tests never
+ * depend on the developer's real dotfiles.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const UNIC_TOKEN = 'unicjsc.com';
+const VISION_MODEL_ALIAS = 'unic-vision';
+
+// Narrow, anchored: a `base_url` key assignment whose quoted value contains the UNIC token.
+// See file header "TOML" note for why this is a regex and not a real parser.
+const CODEX_BASE_URL_UNIC_RE = /\bbase_url\s*=\s*(["'])(?:(?!\1)[^\r\n])*unicjsc\.com(?:(?!\1)[^\r\n])*\1/i;
+
+function safeReadFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function safeReadJson(filePath) {
+  const raw = safeReadFile(filePath);
+  if (raw == null) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function resolveHomeDir(overrideHome) {
+  if (overrideHome) return overrideHome;
+  if (process.env.UKIT_TEST_HOME) return process.env.UKIT_TEST_HOME;
+  return os.homedir();
+}
+
+function resolveRootDir(overrideRoot) {
+  if (overrideRoot) return overrideRoot;
+  if (process.env.UKIT_TEST_ROOT) return process.env.UKIT_TEST_ROOT;
+  return process.cwd();
+}
+
+function probeEnvVar(name) {
+  const value = process.env[name];
+  return typeof value === 'string' && value.includes(UNIC_TOKEN);
+}
+
+function probeClaudeSettings(filePath) {
+  const json = safeReadJson(filePath);
+  const envBlock = json && typeof json === 'object' ? json.env : null;
+  if (!envBlock || typeof envBlock !== 'object') return false;
+  return Object.values(envBlock).some(
+    (value) => typeof value === 'string' && value.includes(UNIC_TOKEN),
+  );
+}
+
+function probeCodexConfig(filePath) {
+  const raw = safeReadFile(filePath);
+  if (raw == null) return false;
+  return CODEX_BASE_URL_UNIC_RE.test(raw);
+}
+
+/**
+ * Presence-only check against a secrets file. Reads the file once, tests for the substring, and
+ * returns a boolean. The raw content is never retained, logged, or returned — it falls out of
+ * scope as soon as this function returns. A read failure (missing file, permission error, etc.)
+ * is swallowed and treated as "no hit"; the error itself is never surfaced (it could, in theory,
+ * embed a path — this function does not let it propagate at all).
+ */
+function probeKiloSecretsPresence(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    return raw.includes(UNIC_TOKEN);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Checks whether the Codex model catalog exists and, if so, whether it lists `unic-vision`.
+ * A missing/unreadable/malformed catalog is never an error — it degrades to "unknown" and the
+ * caller treats that as aliasAvailable: false with an explanatory advisory.
+ */
+function checkCodexVisionAlias(catalogPath) {
+  const json = safeReadJson(catalogPath);
+  if (json == null) {
+    return { checked: false, aliasAvailable: false };
+  }
+  const models = Array.isArray(json?.models)
+    ? json.models
+    : Array.isArray(json)
+      ? json
+      : [];
+  const aliasAvailable = models.some((entry) => {
+    const slug = entry && typeof entry === 'object' ? entry.slug ?? entry.id ?? entry.name : null;
+    return slug === VISION_MODEL_ALIAS;
+  });
+  return { checked: true, aliasAvailable };
+}
+
+/**
+ * Runs all seven probes in the documented order and returns the output contract object. Never
+ * throws — any unexpected error in an individual probe is contained so the overall result still
+ * reflects whatever was determined so far.
+ *
+ * @param {{ rootDir?: string, homeDir?: string }} [options]
+ */
+export function detectUnicGateway(options = {}) {
+  const homeDir = resolveHomeDir(options.homeDir);
+  const rootDir = resolveRootDir(options.rootDir);
+
+  const sources = [];
+  const recordHit = (hit, label) => {
+    if (hit && !sources.includes(label)) sources.push(label);
+  };
+
+  const probes = [
+    () => recordHit(probeEnvVar('ANTHROPIC_BASE_URL'), 'env'),
+    () => recordHit(probeEnvVar('OPENAI_BASE_URL'), 'env'),
+    () => recordHit(probeClaudeSettings(path.join(rootDir, '.claude', 'settings.json')), 'claude-settings'),
+    () => recordHit(probeClaudeSettings(path.join(homeDir, '.claude', 'settings.json')), 'claude-settings'),
+    () => recordHit(probeCodexConfig(path.join(rootDir, '.codex', 'config.toml')), 'codex'),
+    () => recordHit(probeCodexConfig(path.join(homeDir, '.codex', 'config.toml')), 'codex'),
+    () => recordHit(probeKiloSecretsPresence(path.join(homeDir, '.kilocode', 'secrets.json')), 'kilo'),
+  ];
+  for (const probe of probes) {
+    try {
+      probe();
+    } catch {
+      // A single probe failing must never abort detection or throw; skip and continue.
+    }
+  }
+
+  const unicMode = sources.length > 0;
+  const source = sources[0] ?? null;
+
+  let catalogInfo = { checked: false, aliasAvailable: false };
+  try {
+    catalogInfo = checkCodexVisionAlias(path.join(homeDir, '.codex', 'model-catalog.json'));
+  } catch {
+    catalogInfo = { checked: false, aliasAvailable: false };
+  }
+
+  const result = {
+    unicMode,
+    source,
+    sources,
+    visionModel: VISION_MODEL_ALIAS,
+    aliasAvailable: catalogInfo.aliasAvailable,
+  };
+
+  const advisoryParts = [];
+  if (!unicMode) {
+    advisoryParts.push(
+      'No tool on this machine is pointed at the UNIC gateway (unicjsc.com); UNIC routing stays disabled.',
+    );
+  }
+  if (catalogInfo.checked && !catalogInfo.aliasAvailable) {
+    advisoryParts.push(`${VISION_MODEL_ALIAS} not listed in the Codex model catalog; vision requests may fall back.`);
+  }
+  if (advisoryParts.length > 0) {
+    result.advisory = advisoryParts.join(' ');
+  }
+
+  return result;
+}
+
+function formatHuman(result) {
+  const lines = [
+    `unicMode: ${result.unicMode}`,
+    `source: ${result.source ?? '-'}`,
+    `sources: ${result.sources.length > 0 ? result.sources.join(', ') : '-'}`,
+    `visionModel: ${result.visionModel}`,
+    `aliasAvailable: ${result.aliasAvailable}`,
+  ];
+  if (result.advisory) lines.push(`advisory: ${result.advisory}`);
+  return lines.join('\n');
+}
+
+function safeFallbackResult() {
+  return {
+    unicMode: false,
+    source: null,
+    sources: [],
+    visionModel: VISION_MODEL_ALIAS,
+    aliasAvailable: false,
+    advisory: 'unic-gateway detection failed unexpectedly; defaulting to unicMode: false.',
+  };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const jsonMode = args.includes('--json');
+
+  let result;
+  try {
+    result = detectUnicGateway();
+  } catch {
+    result = safeFallbackResult();
+  }
+
+  try {
+    if (jsonMode) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      process.stdout.write(`${formatHuman(result)}\n`);
+    }
+  } catch {
+    // Even output formatting must never throw the process into a non-zero exit.
+  }
+
+  process.exitCode = 0;
+}
+
+const isMainModule = (() => {
+  try {
+    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+  } catch {
+    return false;
+  }
+})();
+
+if (isMainModule) {
+  try {
+    main();
+  } catch {
+    process.exitCode = 0;
+  }
+}

package/templates/CLAUDE.md

@@ -162,6 +162,14 @@ When the same file or symbol fails `debugLoopThreshold` (default: 2) times in on
 
 This is internal orchestration — end users do not need to know about tiers, thresholds, or escalation. The AI handles routing transparently.
 
+### Vision lane (capability, not a cost tier)
+
+`unic-vision` is a **capability lane**, not a fourth cost tier — it is orthogonal to lite/code/smart above and never appears as a row in the tier table. `unic-code` and `unic-smart` cannot read images on the UNIC gateway; they must never guess at image contents.
+
+- **Gateway detection**: seeing `unicjsc.com` in **any** tool's base URL — Claude Code env, Claude settings, Codex config, Kilo, or `OPENAI_BASE_URL` — activates UNIC routing.
+- **Enforcement**: every image (pasted, local file path, or URL) must be analysed by the `ukit-vision-analyst` agent running on `unic-vision` before any related edit happens. `Edit`/`Write` are **hard-blocked** until an analysis receipt exists for every pending image; `Read`/`Grep`/`Glob`/`Bash` stay unblocked so the analyst itself can see the image and write its receipt.
+- This is internal orchestration — end users never invoke a vision command directly; `ukit install` plus natural language remains the whole surface. No new commands.
+
 ## Project Snapshot
 
 - Project: {{project.name}} | Root: {{project.root}}

package/templates/ukit/storage/config.json

@@ -82,6 +82,7 @@
     "advisorEnabled": true,
     "contracts": {
       "tiny-fix": {
+        "modelTier": "lite",
         "maxReadPasses": 0,
         "maxContextPulls": 0,
         "verificationPolicy": "minimal-or-targeted",
@@ -89,6 +90,7 @@
         "delegationPolicy": "disallow"
       },
       "local-fix": {
+        "modelTier": "code",
         "maxReadPasses": 1,
         "maxContextPulls": 1,
         "verificationPolicy": "targeted-if-covered",
@@ -96,6 +98,7 @@
         "delegationPolicy": "disallow"
       },
       "local-build": {
+        "modelTier": "code",
         "maxReadPasses": 2,
         "maxContextPulls": 1,
         "verificationPolicy": "targeted-if-covered",
@@ -103,12 +106,14 @@
         "delegationPolicy": "disallow-by-default"
       },
       "find-cause": {
+        "modelTier": "code",
         "maxReadPassesBeforeReassess": 3,
         "verificationPolicy": "root-cause-then-targeted",
         "completionRule": "never-claim-fixed-without-write-and-verification",
         "delegationPolicy": "allow-specialized-debug-lane"
       },
       "shared-edit": {
+        "modelTier": "code",
         "maxReadPasses": 2,
         "maxContextPulls": 2,
         "verificationPolicy": "targeted-then-widen-on-risk",
@@ -116,6 +121,7 @@
         "delegationPolicy": "allow-qualified-sidecar"
       },
       "map-impact": {
+        "modelTier": "code",
         "maxReadPasses": 3,
         "maxContextPulls": 3,
         "verificationPolicy": "impact-first-then-targeted-then-widen-on-risk",
@@ -123,10 +129,29 @@
         "delegationPolicy": "allow-impact-sidecar"
       },
       "review-release": {
+        "modelTier": "smart",
         "verificationPolicy": "evidence-first",
         "completionRule": "report-findings-not-implementation",
         "delegationPolicy": "allow-review-sidecar"
       }
+    },
+    "modelTiers": {
+      "lite": { "claudeModel": "claude-haiku-4-5", "genericModel": "unic-lite" },
+      "code": { "claudeModel": "claude-sonnet-4-6", "genericModel": "unic-code" },
+      "smart": { "claudeModel": "claude-opus-4-6", "genericModel": "unic-smart" },
+      "vision": {
+        "claudeModel": "unic-vision",
+        "genericModel": "unic-vision",
+        "fallbackModel": "claude-sonnet-4-6",
+        "capabilityTier": true,
+        "note": "Capability tier, not a cost tier. Orthogonal to lite/code/smart — never insert into escalation.tierOrder. fallbackModel is used when unicMode is off."
+      }
+    },
+    "escalation": {
+      "enabled": true,
+      "debugLoopThreshold": 2,
+      "tierOrder": ["lite", "code", "smart"],
+      "cap": "smart"
     }
   },
   "memory": {
@@ -199,6 +224,14 @@
     "enabled": true,
     "smallTaskModel": "unic-lite",
     "smallTaskAgent": "ukit-small-task-maintainer",
+    "visionEnabled": true,
+    "visionModel": "unic-vision",
+    "visionAgent": "ukit-vision-analyst",
+    "visionCacheDir": ".ukit/storage/cache/vision",
+    "visionMaxImages": 3,
+    "visionMaxBytes": 10485760,
+    "visionRetain": 20,
+    "visionSessionTtlHours": 24,
     "smallTaskUseCases": [
       "task-cleanup",
       "compact-decision",