@ngockhoale/ukit 3.1.0 → 3.1.2

package/template_project/.claude/ukit/index/unic-decision.mjs

@@ -181,7 +181,10 @@ function normalizeProbabilities(raw) {
 }
 
 function validateValue(question, args) {
-  const value = args?.value;
+  // The model answers with its native field names — `choice`/`noul`/`score` —
+  // not the schema's `value`; accept both so a live gateway isn't parsed as
+  // malformed.
+  const value = args?.value ?? args?.choice ?? args?.noul ?? args?.score;
   if (question.kind === 'choice') {
     if (typeof value !== 'string') return 'missing-value';
     if (!Array.isArray(question.candidates) || !question.candidates.includes(value)) return 'out-of-enum';
@@ -327,6 +330,44 @@ function pickString(...candidates) {
   return null;
 }
 
+// --- Decision-plane gateway resolution -------------------------------------
+// The decision lane is independent of the host's LLM endpoint: default is the
+// UNIC OpenAI-compatible provider; ~/.ukit/storage/gateway.json {decision:
+// {baseUrl, apiKey, scheme}} overrides; env UKIT_DECISION_BASE_URL /
+// UKIT_DECISION_API_KEY next; the shared UNIC token (ANTHROPIC_*) is the
+// credential fallback so existing installs need nothing extra.
+const DEFAULT_DECISION_BASE_URL = 'https://openai.unicjsc.com';
+const USER_GATEWAY_REL = () => path.join('.ukit', 'storage', 'gateway.json');
+
+function readUserGatewayDecision(homeDir) {
+  if (!homeDir) return null;
+  const json = safeReadJson(path.join(homeDir, USER_GATEWAY_REL()));
+  const decision = json?.decision;
+  return decision && typeof decision === 'object' ? decision : null;
+}
+
+function resolveDecisionBaseUrl({ homeDir, env }) {
+  const fileUrl = pickString(readUserGatewayDecision(homeDir)?.baseUrl);
+  if (fileUrl) return { baseUrl: fileUrl, source: 'ukit-gateway-json' };
+  const envUrl = pickString(env?.UKIT_DECISION_BASE_URL);
+  if (envUrl) return { baseUrl: envUrl, source: 'env' };
+  return { baseUrl: DEFAULT_DECISION_BASE_URL, source: 'default' };
+}
+
+function resolveDecisionApiKey({ projectRoot, homeDir, env }) {
+  const file = readUserGatewayDecision(homeDir);
+  const fileKey = pickString(file?.apiKey);
+  if (fileKey) {
+    const scheme = file?.scheme === 'api-key' ? 'api-key' : 'auth-token';
+    return { value: fileKey, scheme, source: 'ukit-gateway-json' };
+  }
+  const envKey = pickString(env?.UKIT_DECISION_API_KEY);
+  if (envKey) return { value: envKey, scheme: 'auth-token', source: 'env' };
+  const shared = resolveGatewayApiKey({ projectRoot, homeDir, env });
+  if (shared?.value) return { ...shared, source: 'shared-unic-token' };
+  return { value: null, scheme: null, source: null };
+}
+
 function readSettingsEnvBlock(filePath) {
   const json = safeReadJson(filePath);
   if (!json || typeof json !== 'object') return null;
@@ -422,13 +463,14 @@ function readMergedConfig(rootDir, homeDir) {
 
 // ---------------------------------------------------------------------------
 // Client core — mirror of src/decision/client.js semantics minus the circuit
-// breaker (a one-shot CLI has no cross-request state to protect).
-// ---------------------------------------------------------------------------
-
 const DEFAULT_CHECKPOINTS = {
-  default: 'unic-decision/laya-multilingual',
-  english: 'unic-decision/laya',
-  unknownLanguage: 'unic-decision/auto',
+  // Bare 'unic-decision' is the credential-safe alias — the only checkpoint a
+  // freshly-bound UNIC decision key serves. Variants (e.g.
+  // unic-decision-multilingual once the provider binds it) override via
+  // decisionPlane.checkpoints.
+  default: 'unic-decision',
+  english: 'unic-decision',
+  unknownLanguage: 'unic-decision',
 };
 
 const DEFAULT_TIMEOUT_MS = 5000;
@@ -466,9 +508,44 @@ function isTransientStatus(status) {
   return status === 429 || (status >= 500 && status <= 599);
 }
 
+// The UNIC decision endpoint streams the completion even without stream:true —
+// the body is one JSON object followed by an SSE "data: [DONE]" trailer.
+// Parse the first JSON object, ignore the trailer.
+function parseMaybeSse(text) {
+  const trimmed = String(text ?? '').trim();
+  if (!trimmed.startsWith('{')) {
+    // Pure SSE frames: join data payloads.
+    const payload = trimmed
+      .split('\n')
+      .filter((line) => line.startsWith('data:') && !line.includes('[DONE]'))
+      .map((line) => line.slice(5).trim())
+      .join('');
+    return JSON.parse(payload || trimmed);
+  }
+  // JSON object possibly followed by a glued SSE trailer (`}data: [DONE]`,
+  // observed live) — extract the balanced object, strings/comments aware.
+  let depth = 0;
+  for (let i = 0; i < trimmed.length; i += 1) {
+    const ch = trimmed[i];
+    if (ch === '"' || ch === "'") {
+      for (let j = i + 1; j < trimmed.length; j += 1) {
+        if (trimmed[j] === '\\') j += 1;
+        else if (trimmed[j] === ch) { i = j; break; }
+      }
+      continue;
+    }
+    if (ch === '{') depth += 1;
+    else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return JSON.parse(trimmed.slice(0, i + 1));
+    }
+  }
+  return JSON.parse(trimmed);
+}
+
 async function readResponseBody(res) {
+  if (res && typeof res.text === 'function') return parseMaybeSse(await res.text());
   if (res && typeof res.json === 'function') return res.json();
-  if (res && typeof res.text === 'function') return JSON.parse(await res.text());
   return res;
 }
 
@@ -574,14 +651,14 @@ export async function requestBatch(batch, {
     return outcome('blocked-sensitive', { checkpoint });
   }
 
-  const base = resolveGatewayBaseUrl({ projectRoot, homeDir, env });
+  const base = resolveDecisionBaseUrl({ homeDir, env });
   if (!base?.baseUrl) {
     return outcome('unsupported', {
       fallbackCode: 'endpoint-unconfigured',
       checkpoint,
     });
   }
-  const key = resolveGatewayApiKey({ projectRoot, homeDir, env });
+  const key = resolveDecisionApiKey({ projectRoot, homeDir, env });
   const endpoint = {
     url: `${String(base.baseUrl).replace(/\/+$/, '')}/v1/chat/completions`,
     headers: buildAuthHeaders(key),
@@ -621,6 +698,26 @@ export async function requestBatch(batch, {
 
     const status = res?.status ?? (res?.ok === false ? 500 : 200);
     if (res?.ok === false || status < 200 || status >= 300) {
+      // A variant checkpoint without bound credentials (e.g.
+      // unic-decision-multilingual before provider binding) returns a 4xx
+      // model_not_found body — retry once on the bare `unic-decision` model.
+      if (checkpoint !== 'unic-decision') {
+        let notFound = status === 404;
+        try {
+          const clone = typeof res?.clone === 'function' ? res.clone() : null;
+          const errBody = clone ? parseMaybeSse(await clone.text()) : null;
+          if (errBody?.error?.code === 'model_not_found') notFound = true;
+        } catch { /* keep status-based guess */ }
+        if (notFound) {
+          checkpoint = 'unic-decision';
+          try {
+            body = JSON.stringify(
+              encodeBatch({ model: checkpoint, statePacket: serialized, questions }),
+            );
+          } catch { /* keep prior body */ }
+          continue;
+        }
+      }
       if (isTransientStatus(status) && attempt + 1 < maxAttempts) continue;
       if (status === 401 || status === 403) {
         lastError = 'unavailable';
@@ -680,9 +777,9 @@ export async function runHealthProbe({
   const dp = decisionPlaneConfig(config);
   if (dp.enabled === false) return { status: 'unavailable' };
   if (!transport) return { status: 'unsupported' };
-  const base = resolveGatewayBaseUrl({ projectRoot, homeDir, env });
+  const base = resolveDecisionBaseUrl({ homeDir, env });
   if (!base?.baseUrl) return { status: 'unsupported', fallbackCode: 'endpoint-unconfigured' };
-  const key = resolveGatewayApiKey({ projectRoot, homeDir, env });
+  const key = resolveDecisionApiKey({ projectRoot, homeDir, env });
   const checkpoint = resolveCheckpoint('multilingual', config);
   const timeoutMs = Number.isFinite(dp.timeoutMs) ? dp.timeoutMs : DEFAULT_TIMEOUT_MS;
   const body = JSON.stringify({
@@ -789,7 +886,16 @@ async function main() {
 
 const isMainModule = (() => {
   try {
-    return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] ?? '');
+    const invoked = process.argv[1] ?? '';
+    if (!invoked) return false;
+    const self = path.resolve(fileURLToPath(import.meta.url));
+    const target = path.resolve(invoked);
+    if (self === target) return true;
+    // Installed mirrors may be reached through a symlinked directory (e.g.
+    // .codex/ukit -> ../.claude/ukit): realpath resolves the link, basename
+    // equality keeps same-named unrelated scripts from matching.
+    return path.basename(invoked) === 'unic-decision.mjs'
+      && fs.realpathSync(target) === self;
   } catch {
     return false;
   }

package/template_project/.codex/settings.json

@@ -188,6 +188,9 @@
           "compact-now-or-later",
           "summarize-docs-or-keep-detail"
         ],
+        "decisionAdapter": "sidecar-decision.mjs",
+        "decisionStageGate": "decisionPlane.families.workflow.stage",
+        "decisionKeysSource": "cli",
         "stepBudgets": {
           "trivial": {
             "maxSteps": 1,

package/template_project/.omp/agents/code-reviewer.md

@@ -48,6 +48,26 @@ If any input is missing, return `CHANGES-REQUESTED` with reason "incomplete hand
 - **APPROVED-WITH-MINOR** — Minor naming / doc / style issues. Logged on task file but handoff allowed.
 - **APPROVED** — Clean.
 
+### Stage gate — verdict emission (unic-decision)
+
+You generate the findings; the FINAL verdict/bucket classification is a bounded
+decision owned by the local decision model when staged. Read
+`decisionPlane.families.review.stage` from `.ukit/storage/config.json`:
+
+- `off` (default) or any adapter failure (`outcomeClass` ≠ `accepted`/`partial`) →
+  you emit the verdict directly, exactly as today; the deterministic severity
+  aggregate (any critical → CHANGES-REQUESTED; ≥1 important or any
+  unclassified/unknown severity → APPROVED-WITH-MINOR; else APPROVED) stays
+  authoritative.
+- not `off` → emit the verdict via `node .claude/ukit/index/review-verdict.mjs`
+  (registered key `review.verdict.v1`): pipe your extracted findings as JSON on
+  stdin — whitelisted fields only (`id`, `severity`, `file`, `line`, short
+  `claim`; never diff hunks or secrets). Use the adapter's `verdict`/`buckets`
+  fields in the `## Reviewer Verdict` block.
+
+Model isolation is preserved: the verdict pass runs on the local unic-decision
+model, so reviewer ≠ executor still stands.
+
 ### Output (append to task file as `## Reviewer Verdict`)
 
 ```
@@ -139,7 +159,11 @@ additions:
   `node .claude/ukit/index/review-panel-aggregate.mjs <TASK-xxx.md...>` and hands you
   the output, the lead fills `AGREEMENT_MAP` with the emitted finding → members map
   and applies the lead-judgment buckets to every finding: **Act on** / **Consider** /
-  **Noted** / **Dismissed**.
+  **Noted** / **Dismissed**. When `decisionPlane.families.review.stage` is not `off`,
+  the lead's bucketing and panel verdict go through
+  `node .claude/ukit/index/review-verdict.mjs --panel` (`review.finding-bucket.v1` /
+  `review.panel-verdict.v1`) per the stage gate above — the deterministic aggregate
+  stays authoritative at `off` or on adapter failure.
 - `consensus≥2 identical findings = high signal`: a finding reported by two or more
   panel members is high-signal and must not be bucketed below **Consider** without a
   stated reason.

package/template_project/.omp/agents/ukit-small-task-maintainer.md

@@ -27,6 +27,22 @@ You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non
 - Keeping agent context compact without removing existing lanes: Claude PreCompact/reinject stays active and Codex Desktop soft handoffs use `compact.codexContext.compactTarget` (default 150 lines; preferred 120-150; hard max 170) while preserving critical state.
 - Small, reversible UKit runtime maintenance decisions.
 
+## Bounded Decisions (stage-gated unic-decision)
+
+The six bounded decisions enumerated in `.codex/settings.json` `smallTaskModel.decisionPolicy.decisions` — `fast-vs-slow-lane`, `safe-vs-risky-lane`, `skill-routing-needed`, `step-budget-enough`, `compact-now-or-later`, `summarize-docs-or-keep-detail` — consult `unic-decision` first via the installed CLI when the decision-plane stage allows:
+
+```
+node .claude/ukit/index/sidecar-decision.mjs --decision <name> [--root <dir>]   # context JSON on stdin
+```
+
+The CLI resolves `decisionPlane.families.workflow.stage` and owns the name → `workflow.*` decision-key mapping (`--list` prints it):
+
+- `off` (default): the CLI's deterministic rules answer directly — zero transport, authoritative.
+- `shadow`: run the batch for comparison only; the deterministic rule answer stays authoritative.
+- `canary`/`default`: a valid unic-decision answer wins; an invalid or unavailable adapter falls back to the deterministic rule (`outcomeClass: 'unavailable'`).
+
+`unic-decision` is the only model allowed in these decision steps — on any failure the deterministic rule is the fallback, never another LLM for the verdict. This lane's own model (`unic-lite`) keeps generative work only: summarization, doc maintenance, and cleanup — it never emits a verdict for these decisions.
+
 ## Never Use For
 
 - Security/auth/permission/secrets work.