@ngockhoale/ukit 2.4.1 → 2.4.3

package/src/core/gatewayProbe.js

@@ -22,6 +22,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 const GATEWAY_DOC = 'docs/GATEWAY.md';
+const SETTINGS_RELATIVE_PROBE_PATH = path.join('.claude', 'settings.json');
 
 function safeReadFile(filePath) {
   try {
@@ -96,6 +97,53 @@ export async function resolveGatewayBaseUrl({
   return { baseUrl: null, source: null };
 }
 
+function readSettingsEnvBlock(filePath) {
+  const json = safeReadJson(filePath);
+  if (!json || typeof json !== 'object') return null;
+  const envBlock = json.env;
+  if (!envBlock || typeof envBlock !== 'object' || Array.isArray(envBlock)) return null;
+  return envBlock;
+}
+
+/**
+ * Resolves the API key the probe should authenticate with, mirroring the same 3-tier probe
+ * order as `resolveGatewayBaseUrl`: env → project `.claude/settings.json` env → home
+ * `~/.claude/settings.json` env. Plain terminals do not export ANTHROPIC_* (Claude Code
+ * injects its settings env only into its own sessions), so without the settings tiers
+ * `ukit doctor --gateway` probes keyless and misreports an auth-gated gateway.
+ *
+ * The `scheme` field mirrors `pickApiKey`'s source (`'api-key'` → x-api-key,
+ * `'auth-token'` → Authorization: Bearer) so callers can pass it straight into
+ * `probeGateway` as `apiKeySource`. Never throws.
+ *
+ * @param {{ projectRoot: string, homeDir?: string, env?: object }} options
+ * @returns {{ value: string|null, scheme: 'api-key'|'auth-token'|null,
+ *             source: 'env'|'claude-settings'|null }}
+ */
+export function resolveGatewayApiKey({
+  projectRoot,
+  homeDir = os.homedir(),
+  env = process.env,
+} = {}) {
+  const envKey = pickApiKey(env ?? {});
+  if (envKey) {
+    return { value: envKey.value, scheme: envKey.source, source: 'env' };
+  }
+  const settingsPaths = [
+    ...(projectRoot ? [path.join(projectRoot, SETTINGS_RELATIVE_PROBE_PATH)] : []),
+    path.join(homeDir, SETTINGS_RELATIVE_PROBE_PATH),
+  ];
+  for (const settingsPath of settingsPaths) {
+    const envBlock = readSettingsEnvBlock(settingsPath);
+    if (!envBlock) continue;
+    const key = pickApiKey(envBlock);
+    if (key) {
+      return { value: key.value, scheme: key.source, source: 'claude-settings' };
+    }
+  }
+  return { value: null, scheme: null, source: null };
+}
+
 function pickApiKey(envLike) {
   if (!envLike || typeof envLike !== 'object') return null;
   // Source matters: ANTHROPIC_API_KEY is sent by Claude Code as `x-api-key`, while
@@ -112,7 +160,16 @@ function pickApiKey(envLike) {
 
 function pickModel(envLike) {
   if (!envLike || typeof envLike !== 'object') return null;
-  return pickString(envLike.ANTHROPIC_MODEL);
+  // ANTHROPIC_MODEL wins, then the per-lane alias mappings Claude Code itself resolves
+  // (2026-09-16 live evidence: alias-based gateways provision ONLY the mapped lane models;
+  // probing the built-in default `claude-sonnet-4-5` returned HTTP 404 `model_not_found` /
+  // "No active credentials for provider: claude" on a gateway whose real sessions work).
+  return pickString(
+    envLike.ANTHROPIC_MODEL,
+    envLike.ANTHROPIC_DEFAULT_OPUS_MODEL,
+    envLike.ANTHROPIC_DEFAULT_SONNET_MODEL,
+    envLike.ANTHROPIC_DEFAULT_HAIKU_MODEL,
+  );
 }
 
 // Minimal VALID Anthropic Messages API body. The probe only measures transport shape
@@ -132,11 +189,14 @@ function buildRequestBody({ stream, model }) {
 //   * ANTHROPIC_API_KEY     -> x-api-key (Anthropic-native)
 //   * ANTHROPIC_AUTH_TOKEN  -> Authorization: Bearer (OpenAI-style / proxy gateways)
 // Without this split, token-auth gateways 401 the probe even when transport shape is
-// valid (Reviewer Round-1 important finding #3).
+// valid (Reviewer Round-1 important finding #3). `anthropic-version` is sent for BOTH
+// schemes: it is required by Anthropic-native gateways and ignored by OpenAI-style proxies
+// (2026-09-16 live evidence: the token-auth UNIC gateway returns 200 + valid Message with
+// the header present).
 function buildAuthHeaders(keyValue, keySource) {
   if (!keyValue) return {};
   if (keySource === 'auth-token') {
-    return { Authorization: `Bearer ${keyValue}` };
+    return { Authorization: `Bearer ${keyValue}`, 'anthropic-version': '2023-06-01' };
   }
   // Default to the Anthropic-native scheme — covers explicit apiKey arg and
   // ANTHROPIC_API_KEY env (the dominant case).
@@ -161,6 +221,62 @@ function parseSseEvents(text) {
   return count;
 }
 
+// TASK-010 (error-body surfacing): on a non-OK response the gateway body often carries the
+// operator-actionable cause (2026-09-16 live evidence: HTTP 404 + `{"error":{"message":"No
+// active credentials for provider: anthropic"}}`). The read is bounded and the surfaced
+// message is capped at 300 chars (PLAN §3/§4 contract) so a giant HTML error page can never
+// flood the doctor output.
+const ERROR_DETAIL_MAX_CHARS = 300;
+const ERROR_BODY_MAX_CHARS = 4096;
+
+async function readBodyTextBounded(response) {
+  const body = response?.body;
+  if (!body || typeof body.getReader !== 'function') return '';
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let text = '';
+  try {
+    while (text.length < ERROR_BODY_MAX_CHARS) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (value) text += decoder.decode(value, { stream: true });
+    }
+  } catch {
+    // A failing/unreadable error body must never turn into a probe crash — fall back to
+    // whatever was collected so far (possibly empty).
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // reader may already be released
+    }
+  }
+  return text;
+}
+
+/**
+ * Extracts the gateway error message from a non-OK response body:
+ * `JSON.parse(text).error.message`, truncated to `ERROR_DETAIL_MAX_CHARS`. Returns `null`
+ * when the body is missing, unreadable, non-JSON, or carries no error message — callers
+ * then leave `errorDetail` unset and keep today's `HTTP <status>` wording. Never throws.
+ */
+async function extractErrorDetail(response) {
+  const text = await readBodyTextBounded(response);
+  if (!text) return null;
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const message =
+    parsed && typeof parsed === 'object' && typeof parsed?.error?.message === 'string'
+      ? parsed.error.message
+      : null;
+  if (!message) return null;
+  return message.slice(0, ERROR_DETAIL_MAX_CHARS);
+}
+
 /**
  * Streaming probe: posts `stream: true` and counts SSE frames + distinct body reads.
  *
@@ -169,7 +285,8 @@ function parseSseEvents(text) {
  * buffering gateway dumps everything in one read.
  *
  * @returns {Promise<{ ok: boolean, eventsReceived: number, firstEventMs: number|null,
- *                    chunks: number, buffered: boolean, error?: string }>}
+ *                    chunks: number, buffered: boolean, error?: string,
+ *                    errorDetail?: string|null }>}
  */
 async function runStreamingProbe({ url, headers, body: requestBody, fetchImpl, timeoutMs }) {
   const controller = new AbortController();
@@ -190,6 +307,7 @@ async function runStreamingProbe({ url, headers, body: requestBody, fetchImpl, t
         chunks: 0,
         buffered: false,
         error: `HTTP ${response?.status ?? 'unknown'}`,
+        errorDetail: await extractErrorDetail(response),
       };
     }
     const body = response.body;
@@ -278,7 +396,8 @@ async function runStreamingProbe({ url, headers, body: requestBody, fetchImpl, t
  * gateway error envelope slip through Claude Code's retry path and kill the user's turn.
  *
  * @returns {Promise<{ ok: boolean, httpOk: boolean, isAnthropicMessage: boolean,
- *                    requestIdPresent: boolean, bodyBytes: number|null, error?: string }>}
+ *                    requestIdPresent: boolean, bodyBytes: number|null, error?: string,
+ *                    errorDetail?: string|null }>}
  */
 async function runNonStreamingProbe({ url, headers, body: requestBody, fetchImpl, timeoutMs }) {
   const controller = new AbortController();
@@ -300,6 +419,7 @@ async function runNonStreamingProbe({ url, headers, body: requestBody, fetchImpl
         requestIdPresent,
         bodyBytes: null,
         error: `HTTP ${response?.status ?? 'unknown'}`,
+        errorDetail: await extractErrorDetail(response),
       };
     }
     const body = response.body;
@@ -341,7 +461,12 @@ async function runNonStreamingProbe({ url, headers, body: requestBody, fetchImpl
       typeof parsed === 'object' &&
       parsed.type === 'message' &&
       Array.isArray(parsed.content);
-    const ok = isAnthropicMessage && requestIdPresent;
+    // 2026-09-16 live re-classification: the real UNIC gateway returns HTTP 200 + a valid
+    // Anthropic Message with NO request-id header, and real sessions complete fine — the
+    // hard pass/fail gate is the Message shape (which still catches the 888-byte error-
+    // envelope class). A missing request-id is reported as an advisory hint instead of a
+    // hard fail; see GATEWAY_DOC §3.
+    const ok = isAnthropicMessage;
     return {
       ok,
       httpOk: true,
@@ -406,11 +531,12 @@ export async function probeGateway({
   if (!streaming.ok) {
     if (streaming.buffered) {
       hints.push(
-        `Set CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000 in .claude/settings.json env — gateway appears to buffer the entire stream; see ${GATEWAY_DOC}.`,
+        `Gateway buffers the entire stream (the stall signature). Managed posture: keep CLAUDE_STREAM_IDLE_TIMEOUT_MS low so the idle watchdog fires, and keep the non-streaming fallback ENABLED so the aborted stream recovers via a non-streaming retry; see ${GATEWAY_DOC}.`,
       );
     } else if (streaming.error) {
+      const gatewayCause = streaming.errorDetail ? ` — ${streaming.errorDetail}` : '';
       hints.push(
-        `Streaming probe failed: ${streaming.error} — see ${GATEWAY_DOC}.`,
+        `Streaming probe failed: ${streaming.error}${gatewayCause} (probed model: ${effectiveModel}) — see ${GATEWAY_DOC}.`,
       );
     } else {
       hints.push(
@@ -421,21 +547,23 @@ export async function probeGateway({
   if (!nonStreaming.ok) {
     if (nonStreaming.httpOk && !nonStreaming.isAnthropicMessage) {
       hints.push(
-        `Set CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 in .claude/settings.json env — non-streaming route returned JSON but not an Anthropic Message; see ${GATEWAY_DOC}.`,
-      );
-    } else if (nonStreaming.httpOk && !nonStreaming.requestIdPresent) {
-      hints.push(
-        `Gateway must set the request-id (or anthropic-request-id) response header — see ${GATEWAY_DOC}.`,
+        `Non-streaming route returned JSON but not an Anthropic Message — leave CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 (fallback must stay off); see ${GATEWAY_DOC}.`,
       );
     } else if (nonStreaming.error) {
+      const gatewayCause = nonStreaming.errorDetail ? ` — ${nonStreaming.errorDetail}` : '';
       hints.push(
-        `Non-streaming probe failed: ${nonStreaming.error} — see ${GATEWAY_DOC}.`,
+        `Non-streaming probe failed: ${nonStreaming.error}${gatewayCause} (probed model: ${effectiveModel}) — see ${GATEWAY_DOC}.`,
       );
     } else {
       hints.push(`Non-streaming probe failed — see ${GATEWAY_DOC}.`);
     }
   }
+  if (nonStreaming.httpOk && nonStreaming.isAnthropicMessage && !nonStreaming.requestIdPresent) {
+    hints.push(
+      `Gateway did not set a request-id (or anthropic-request-id) header — advisory only, diagnosability is degraded but transport works; see ${GATEWAY_DOC}.`,
+    );
+  }
 
   const verdict = streaming.ok && nonStreaming.ok ? 'pass' : 'fail';
-  return { streaming, nonStreaming, verdict, hints };
+  return { streaming, nonStreaming, verdict, hints, model: effectiveModel };
 }

package/src/core/gatewayResilienceEnv.js

@@ -4,14 +4,24 @@ import os from 'node:os';
 import path from 'node:path';
 
 // Managed defaults that keep Claude Code responsive when it is pointed at a custom
-// gateway (any non-empty ANTHROPIC_BASE_URL). `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK='1'`
-// forces streaming mode so the client never falls back to a non-streaming POST that can
-// stall for minutes waiting for the full response. `CLAUDE_STREAM_IDLE_TIMEOUT_MS='600000'`
-// raises Claude Code's internal idle timeout from its default (the gateway-side keep-alive
-// can sit idle longer than the default when the upstream is slow).
+// gateway (any non-empty ANTHROPIC_BASE_URL). Posture since 2.4.2 — "fail fast, recover
+// via non-streaming" — based on 2026-09-16 live probes of the stall-class gateway:
+//   * The gateway buffers entire streams (23 SSE events delivered in ONE body read), so a
+//     long generation is silent until it finishes and Claude Code's stream-idle watchdog
+//     is the only thing that can end the silence. `CLAUDE_STREAM_IDLE_TIMEOUT_MS='120000'`
+//     bounds that dead air to 2 minutes instead of hanging for 10.
+//   * The non-streaming route is HEALTHY on the stall-class gateway (HTTP 200 + valid
+//     Anthropic Message), and a non-streaming POST has no idle watchdog at all — it is the
+//     one request shape that reliably survives a buffered long generation. So the fallback
+//     must stay ENABLED (`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK='0'`); disabling it
+//     (the 2.3.16–2.4.1 posture) removed the only recovery path and turned stalls into
+//     silent freezes the user had to interrupt by hand.
 //
 // These are written ONLY when no user-set value already lives in the project's
-// `.claude/settings.json` env block — never clobber, always preserve. Re-running
+// `.claude/settings.json` env block — never clobber, always preserve — EXCEPT for values
+// equal to `GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS` (the shipped defaults of
+// 2.3.16–2.4.1): those were written by UKit itself, so they migrate to the current
+// defaults on the next install instead of being mistaken for user intent. Re-running
 // `ukit install` is a no-op once the keys are in place.
 //
 // Probe order mirrors `templates/.claude/ukit/index/unic-gateway.mjs` (env → project
@@ -21,12 +31,22 @@ import path from 'node:path';
 // is pointed at ANY gateway, so we apply resilience regardless of vendor.
 
 export const GATEWAY_RESILIENCE_ENV_DEFAULTS = Object.freeze({
+  CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '0',
+  CLAUDE_STREAM_IDLE_TIMEOUT_MS: '120000',
+});
+
+// Values shipped as the managed defaults by 2.3.16–2.4.1. A settings env key holding one
+// of these exact values was written by UKit, not by the user, so `applyGatewayResilienceEnv`
+// migrates it to the current default. A user who deliberately tuned a value always uses a
+// non-shipped number (e.g. '300000', '900000') and stays untouched.
+export const GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS = Object.freeze({
   CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK: '1',
   CLAUDE_STREAM_IDLE_TIMEOUT_MS: '600000',
 });
 
 const BASE_URL_ENV_VAR = 'ANTHROPIC_BASE_URL';
 const SETTINGS_RELATIVE_PATH = path.join('.claude', 'settings.json');
+const PROFILE_RELATIVE_PATH = path.join('.claude', 'profile');
 
 function readBaseUrlFromEnvValue(value) {
   return typeof value === 'string' && value.trim().length > 0 ? value : null;
@@ -124,6 +144,7 @@ function backupPathFor(settingsPath) {
  *   applied: string[],
  *   unchanged: string[],
  *   skipped: string[],
+ *   migrated: string[],
  *   changed: boolean,
  *   reason?: string,
  * }>}
@@ -162,6 +183,7 @@ export async function applyGatewayResilienceEnv({
         applied: [],
         unchanged: [],
         skipped: [],
+        migrated: [],
         changed: false,
         reason: `failed to read settings: ${error?.message ?? String(error)}`,
       };
@@ -180,6 +202,7 @@ export async function applyGatewayResilienceEnv({
         applied: [],
         unchanged: [],
         skipped: [],
+        migrated: [],
         changed: false,
         reason: `failed to parse settings JSON: ${error?.message ?? String(error)}`,
       };
@@ -204,6 +227,7 @@ export async function applyGatewayResilienceEnv({
   const applied = [];
   const unchanged = [];
   const skipped = [];
+  const migrated = [];
   let mutated = false;
 
   for (const [key, defaultValue] of Object.entries(GATEWAY_RESILIENCE_ENV_DEFAULTS)) {
@@ -218,6 +242,18 @@ export async function applyGatewayResilienceEnv({
       unchanged.push(key);
       continue;
     }
+    // A value equal to a previously-shipped UKit default was written by UKit itself —
+    // migrate it to the current default instead of treating it as user intent.
+    if (
+      typeof currentValue === 'string' &&
+      currentValue === GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS[key]
+    ) {
+      settings.env[key] = defaultValue;
+      applied.push(key);
+      migrated.push(key);
+      mutated = true;
+      continue;
+    }
     // User owns a non-default value — never touch it.
     skipped.push(key);
   }
@@ -228,6 +264,7 @@ export async function applyGatewayResilienceEnv({
       applied,
       unchanged,
       skipped,
+      migrated,
       changed: false,
     };
   }
@@ -243,6 +280,7 @@ export async function applyGatewayResilienceEnv({
     applied,
     unchanged,
     skipped,
+    migrated,
     changed: true,
   };
 }
@@ -271,7 +309,11 @@ export function formatGatewayResilienceReport(report) {
   );
 
   for (const key of report.applied || []) {
-    lines.push(`  - ${key} = ${JSON.stringify(GATEWAY_RESILIENCE_ENV_DEFAULTS[key])} (applied)`);
+    const legacyValue = GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS[key];
+    const migrated = (report.migrated || []).includes(key) && legacyValue !== undefined;
+    lines.push(
+      `  - ${key} = ${JSON.stringify(GATEWAY_RESILIENCE_ENV_DEFAULTS[key])}${migrated ? ` (migrated from previous UKit default ${JSON.stringify(legacyValue)})` : ' (applied)'}`,
+    );
   }
   for (const key of report.unchanged || []) {
     lines.push(`  - ${key} = ${JSON.stringify(GATEWAY_RESILIENCE_ENV_DEFAULTS[key])} (already set)`);
@@ -290,3 +332,90 @@ export function formatGatewayResilienceReport(report) {
 
   return lines;
 }
+
+/**
+ * Advisory presence scan of the per-profile settings files under
+ * `<homeDir>/.claude/profile/`. A session launched with
+ * `--settings ~/.claude/profile/<name>.json` bypasses `~/.claude/settings.json` entirely, so
+ * a managed resilience key can be absent exactly where it matters while every other check
+ * reports green. This is the delivery-gap detector for that hole.
+ *
+ * Presence-check only — never a value-check. After the documented posture flip the values
+ * are user/machine-owned (a profile may legitimately hold a legacy `'1'`/`'600000'` pair or a
+ * tuned number), so "is the key present" is the whole contract and no value is compared
+ * against `GATEWAY_RESILIENCE_ENV_DEFAULTS`.
+ *
+ * Only regular files ending in `.json` are scanned (sorted by name); decoys that live in the
+ * real profile dir — backups like `x.json.bak-20260916`, `notes.sh`, and subdirectories — are
+ * ignored, and the scan is not recursive. An absent profile directory is not an error: it
+ * resolves `{ scanned: [], compliant: true }` so a machine that never used profiles stays
+ * quiet. Never throws: an unreadable directory, unreadable file, or invalid JSON is
+ * reflected in the per-file result instead of propagating.
+ *
+ * @param {{ homeDir?: string, profileDir?: string|null, keys?: string[]|null }} [options]
+ * @returns {Promise<{ profileDir: string, scanned: Array<{ file: string, validJson: boolean, hasEnvBlock: boolean, missing: string[] }>, compliant: boolean }>}
+ */
+export async function scanProfileResilienceEnv({
+  homeDir = os.homedir(),
+  profileDir = null,
+  keys = null,
+} = {}) {
+  const resolvedProfileDir = profileDir || path.join(homeDir, PROFILE_RELATIVE_PATH);
+  const managedKeys = Array.isArray(keys) && keys.length > 0
+    ? keys
+    : Object.keys(GATEWAY_RESILIENCE_ENV_DEFAULTS);
+
+  const emptyResult = { profileDir: resolvedProfileDir, scanned: [], compliant: true };
+
+  let entries;
+  try {
+    entries = await fs.readdir(resolvedProfileDir, { withFileTypes: true });
+  } catch {
+    // Absent (ENOENT) or unreadable (EACCES) profile dir — nothing to warn about.
+    return emptyResult;
+  }
+
+  const jsonFiles = entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+    .map((entry) => entry.name)
+    .sort();
+
+  if (jsonFiles.length === 0) {
+    return emptyResult;
+  }
+
+  const scanned = [];
+  for (const name of jsonFiles) {
+    const file = path.join(resolvedProfileDir, name);
+    let raw;
+    try {
+      raw = await fs.readFile(file, 'utf8');
+    } catch {
+      scanned.push({ file, validJson: false, hasEnvBlock: false, missing: [...managedKeys] });
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      scanned.push({ file, validJson: false, hasEnvBlock: false, missing: [...managedKeys] });
+      continue;
+    }
+
+    const envBlock = parsed?.env;
+    const hasEnvBlock =
+      Boolean(envBlock) && typeof envBlock === 'object' && !Array.isArray(envBlock);
+    const missing = hasEnvBlock
+      ? managedKeys.filter((key) => !(key in envBlock))
+      : [...managedKeys];
+
+    scanned.push({ file, validJson: true, hasEnvBlock, missing });
+  }
+
+  return {
+    profileDir: resolvedProfileDir,
+    scanned,
+    compliant: scanned.every((entry) => entry.missing.length === 0),
+  };
+}