@kal-elsam/kairo-runtime 0.15.0 → 0.17.0

package/src/global/observability/codex-models.js

@@ -0,0 +1,96 @@
+import { spawn as defaultSpawn } from "node:child_process";
+
+// Real per-account model catalog via Codex's app-server JSON-RPC protocol
+// (`model/list`, confirmed present in `codex app-server generate-json-schema`
+// output and verified live) — never the static, possibly-stale documented
+// list. Same fail-closed shape as codex-usage.js: any error yields
+// `unknown`, never a fabricated model.
+const DEFAULT_TIMEOUT_MS = 2500;
+const SOURCE = "codex app-server model/list";
+
+function unknown(error = null) {
+  return { status: "unknown", source: SOURCE, models: [], error: error ? String(error) : null };
+}
+
+function writeRequest(child, id, method, params) {
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+}
+
+function normalizeModel(entry) {
+  return {
+    id: entry.id,
+    displayName: entry.displayName ?? entry.id,
+    isDefault: entry.isDefault === true,
+    hidden: entry.hidden === true
+  };
+}
+
+/**
+ * Reads Codex's real, currently-available model catalog for this
+ * authenticated account — not a static documented list. Excludes hidden
+ * models by default (mirrors what Codex's own picker would offer).
+ */
+export async function readCodexModels({
+  spawn = defaultSpawn,
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  includeHidden = false
+} = {}) {
+  let child;
+  try {
+    child = spawn("codex", ["app-server", "--listen", "stdio://"], {
+      cwd,
+      env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch (error) {
+    return unknown(error?.message ?? error);
+  }
+
+  return new Promise((resolve) => {
+    let buffer = "";
+    let listRequestId = null;
+    let finished = false;
+    const timer = setTimeout(() => finish(unknown("codex app-server timeout")), timeoutMs);
+
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      try { child.kill?.(); } catch { /* best effort */ }
+      resolve(result);
+    }
+
+    function onLine(line) {
+      let message;
+      try { message = JSON.parse(line); } catch { return finish(unknown("malformed codex app-server output")); }
+      if (!message || typeof message !== "object" || message.id == null) return;
+      if (message.error) return finish(unknown(`codex app-server error: ${message.error.message ?? "request failed"}`));
+      if (message.id === 1) {
+        listRequestId = 2;
+        writeRequest(child, listRequestId, "model/list", { includeHidden });
+        return;
+      }
+      if (message.id === listRequestId) {
+        const data = Array.isArray(message.result?.data) ? message.result.data : null;
+        if (!data) return finish(unknown("codex returned no model list"));
+        finish({ status: "measured", source: SOURCE, models: data.map(normalizeModel), error: null });
+      }
+    }
+
+    child.stdout?.on("data", (chunk) => {
+      buffer += String(chunk);
+      const lines = buffer.split(/\r?\n/);
+      buffer = lines.pop() ?? "";
+      for (const line of lines) if (line.trim()) onLine(line.trim());
+    });
+    child.once?.("error", (error) => finish(unknown(error?.message ?? error)));
+    child.once?.("close", () => { if (!finished) finish(unknown("codex app-server closed before model list")); });
+
+    writeRequest(child, 1, "initialize", {
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.17.0" },
+      capabilities: {}
+    });
+  });
+}

package/src/global/observability/codex-usage.js

@@ -0,0 +1,160 @@
+import { spawn as defaultSpawn } from "node:child_process";
+
+const DEFAULT_TIMEOUT_MS = 2500;
+const SOURCE = "codex app-server account/rateLimits/read";
+
+function clampPercent(value) {
+  const number = Number(value);
+  if (!Number.isFinite(number)) return null;
+  return Math.max(0, Math.min(100, number));
+}
+
+function epochSecondsToIso(value) {
+  try {
+    const date = new Date(Number(value) * 1000);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+  } catch {
+    return null;
+  }
+}
+
+function normalizeWindow(name, value) {
+  if (!value || typeof value !== "object") return null;
+  const usedPercent = clampPercent(value.usedPercent ?? value.used_percentage);
+  if (usedPercent == null) return null;
+  const windowDurationMins = Number(value.windowDurationMins ?? value.window_duration_mins);
+  const resetsAt = value.resetsAt ?? value.resets_at ?? null;
+  const numericReset = (typeof resetsAt === "number" && Number.isFinite(resetsAt))
+    || (typeof resetsAt === "string" && resetsAt.trim() !== "" && Number.isFinite(Number(resetsAt)));
+  const resetsAtIso = numericReset
+    ? epochSecondsToIso(resetsAt)
+    : (typeof resetsAt === "string" ? resetsAt : null);
+  return {
+    name,
+    usedPercent,
+    remainingPercent: 100 - usedPercent,
+    // Short aliases keep the normalized contract convenient for consumers
+    // while the explicit Percent fields make units unambiguous in the UI.
+    used: usedPercent,
+    remaining: 100 - usedPercent,
+    windowDurationMins: Number.isFinite(windowDurationMins) ? windowDurationMins : null,
+    // The app-server contract uses epoch seconds. Preserve that value and
+    // provide an ISO projection for human-facing clients.
+    resetsAt: numericReset ? Number(resetsAt) : (typeof resetsAt === "string" ? resetsAt : null),
+    resetsAtIso
+  };
+}
+
+/** Normalize only safe, displayable rate-limit fields. Never returns account ids/credits. */
+export function normalizeCodexRateLimits(payload) {
+  const root = payload?.rateLimits ?? payload?.rate_limits ?? payload ?? {};
+  const primary = normalizeWindow("5h", root.primary);
+  const secondary = normalizeWindow("weekly", root.secondary);
+  // Current Codex returns this beside `rateLimits`; accept the older nested
+  // placement only as a compatibility fallback.
+  const ordinaryUsageAllowed = payload?.ordinaryUsageAllowed
+    ?? payload?.ordinary_usage_allowed
+    ?? root.ordinaryUsageAllowed
+    ?? root.ordinary_usage_allowed;
+  const allowed = typeof ordinaryUsageAllowed === "boolean" ? ordinaryUsageAllowed : null;
+  if (!primary && !secondary && allowed == null) return null;
+  return {
+    status: allowed === false ? "exhausted" : "measured",
+    source: SOURCE,
+    ordinaryUsageAllowed: allowed,
+    windows: [primary, secondary].filter(Boolean),
+    primary,
+    secondary
+  };
+}
+
+function unknown(error = null) {
+  return {
+    status: "unknown",
+    source: SOURCE,
+    ordinaryUsageAllowed: null,
+    windows: [],
+    primary: null,
+    secondary: null,
+    error: error ? String(error) : null
+  };
+}
+
+function writeRequest(child, id, method, params) {
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+}
+
+/**
+ * Read Codex subscription rate limits without starting a model turn.
+ * This is deliberately fail-closed: malformed output, unavailable auth, or a
+ * timeout produces `unknown`, never a fabricated quota or a PAYG fallback.
+ */
+export async function readCodexUsage({
+  spawn = defaultSpawn,
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+} = {}) {
+  let child;
+  try {
+    child = spawn("codex", ["app-server", "--listen", "stdio://"], {
+      cwd,
+      env,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+  } catch (error) {
+    return unknown(error?.message ?? error);
+  }
+
+  return new Promise((resolve) => {
+    let buffer = "";
+    let nextId = 2;
+    let rateRequestId = null;
+    let finished = false;
+    const timer = setTimeout(() => finish(unknown("codex app-server timeout")), timeoutMs);
+
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      try { child.kill?.(); } catch { /* best effort */ }
+      resolve(result);
+    }
+
+    function onLine(line) {
+      let message;
+      try { message = JSON.parse(line); } catch { return finish(unknown("malformed codex app-server output")); }
+      if (!message || typeof message !== "object") return;
+      // Notifications have no id and must not affect the request state.
+      if (message.id == null) return;
+      if (message.error) return finish(unknown(`codex app-server error: ${message.error.message ?? "request failed"}`));
+      if (message.id === 1) {
+        rateRequestId = nextId++;
+        writeRequest(child, rateRequestId, "account/rateLimits/read", {
+          excludeResetCreditDetails: true,
+          supportsLunaReserve: false
+        });
+        return;
+      }
+      if (message.id === rateRequestId) {
+        finish(normalizeCodexRateLimits(message.result) ?? unknown("codex returned unusable rate limits"));
+      }
+    }
+
+    child.stdout?.on("data", (chunk) => {
+      buffer += String(chunk);
+      const lines = buffer.split(/\r?\n/);
+      buffer = lines.pop() ?? "";
+      for (const line of lines) if (line.trim()) onLine(line.trim());
+    });
+    child.once?.("error", (error) => finish(unknown(error?.message ?? error)));
+    child.once?.("close", () => { if (!finished) finish(unknown("codex app-server closed before rate limits")); });
+
+    writeRequest(child, 1, "initialize", {
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.17.0" },
+      capabilities: {}
+    });
+  });
+}
+
+export const CODEX_USAGE_SOURCE = SOURCE;

package/src/global/observability/cursor-auth.js

@@ -0,0 +1,88 @@
+import { spawn as defaultSpawn } from "node:child_process";
+import { tmpdir } from "node:os";
+
+// `cursor-agent status`/`whoami` do NOT reliably reflect whether a real
+// invocation will actually work — verified empirically: on this machine
+// `status` reports "Logged in" (exit 0) while a real `cursor-agent -p`
+// call fails outright with "Authentication required. Please run 'agent
+// login' first, or set CURSOR_API_KEY environment variable." `models`
+// behaves the same way (a clean "No models available for this account."
+// even while the session is actually unusable for real invocation).
+//
+// So the only decisive signal for "can Cursor actually be invoked right
+// now" is a real invocation attempt. This probe uses the cheapest one
+// available: a harmless -p call whose failure mode, when unauthenticated,
+// is a local, near-instant CLI rejection (no network round trip) — it
+// has NOT been confirmed whether a genuinely authenticated probe call
+// itself consumes real usage, so this should only be called where a real
+// eligibility decision is actually needed, not on a hot path.
+//
+// --trust is required here too (verified empirically — the probe's cwd,
+// an OS tmpdir cursor-agent has never seen, otherwise triggers an
+// interactive "Workspace Trust Required" prompt that blocks non-
+// interactive use, exactly like a real Bootstrap Analysis snapshot dir
+// would without it).
+// A real -p call to a real model has been observed taking just over
+// 20s — verified empirically, not assumed — so this needs real margin,
+// not a tight bound.
+const DEFAULT_TIMEOUT_MS = 45_000;
+const SOURCE = "cursor-agent -p (probe)";
+const AUTH_REQUIRED_PATTERN = /authentication required/i;
+
+function unknown(error = null) {
+  return { authenticated: false, status: "unknown", source: SOURCE, reason: error ? String(error) : null };
+}
+
+/**
+ * Real, decisive probe for whether Cursor can actually be invoked right
+ * now — NOT whether `status`/`whoami` merely claim it can.
+ * @returns {Promise<{authenticated: boolean, status: "measured"|"unknown", source: string, reason: string|null}>}
+ */
+export async function probeCursorAuth({
+  spawn = defaultSpawn,
+  cwd = tmpdir(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+} = {}) {
+  const args = [
+    "-p", "Reply with the single word: ok", "--output-format", "json",
+    "--mode", "ask", "--sandbox", "enabled", "--workspace", cwd, "--trust"
+  ];
+  let child;
+  try {
+    child = spawn("cursor-agent", args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+  } catch (error) {
+    return unknown(error?.message ?? error);
+  }
+
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let finished = false;
+    const timer = setTimeout(() => finish(unknown("cursor-agent -p probe timed out")), timeoutMs);
+
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      try { child.kill?.(); } catch { /* best effort */ }
+      resolve(result);
+    }
+
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.stderr?.on("data", (chunk) => { stderr += chunk; });
+    child.once?.("error", (error) => finish(unknown(error?.message ?? error)));
+    child.once?.("close", (code, signal) => {
+      const combined = `${stdout}\n${stderr}`;
+      if (AUTH_REQUIRED_PATTERN.test(combined)) {
+        return finish({
+          authenticated: false, status: "measured", source: SOURCE,
+          reason: "cursor-agent reports \"Authentication required\" — the CLI's session/keychain is not actually usable for a real invocation, regardless of what `status`/`models` claim."
+        });
+      }
+      if (signal) return finish(unknown(`cursor-agent -p probe was killed by signal ${signal}${stderr ? `: ${stderr.trim()}` : ""}`));
+      if (code !== 0) return finish(unknown(`cursor-agent -p probe exited with code ${code}${stderr ? `: ${stderr.trim()}` : ""}`));
+      finish({ authenticated: true, status: "measured", source: SOURCE, reason: null });
+    });
+  });
+}

package/src/global/observability/cursor-models.js

@@ -0,0 +1,101 @@
+import { spawn as defaultSpawn } from "node:child_process";
+
+// Real per-account model list via `cursor-agent models`. The populated
+// shape below was captured from the real CLI against a real authenticated
+// account with real models enabled (one `<id> - <Display Name>` entry per
+// line, plus a leading "Available models" header and a trailing "Tip: use
+// --model <id>..." line) — not assumed, not the earlier placeholder
+// parser that predated ever seeing a real populated catalog.
+//
+// A process crash (killed by a signal) or a non-zero exit is never
+// reinterpreted as a clean "no models" answer — an empty/partial stdout
+// from a crash mid-run parses identically to a genuine empty catalog, so
+// exit status is the only real signal that tells them apart. Only a clean
+// exit (code 0, no signal) is trusted; anything else yields `status:
+// "unknown"` with the real stderr, never a fabricated empty catalog.
+const DEFAULT_TIMEOUT_MS = 8_000;
+const SOURCE = "cursor-agent models";
+const ANSI_PATTERN = /\x1b\[[0-9;]*[a-zA-Z]/g;
+const NO_MODELS_SENTINEL = /no models available/i;
+const LOADING_LINE = /^loading models/i;
+// Real model line shape: "<id> - <Display Name>", id has no spaces (every
+// real id observed is a bare slug like "gpt-5.3-codex-low" or "auto").
+// Header ("Available models") and the trailing "Tip: ..." line never
+// match this — no line-anchored " - " separator — so they're dropped
+// without needing to special-case their exact text.
+const MODEL_LINE_PATTERN = /^(\S+)\s-\s(.+)$/;
+
+function unknown(error = null) {
+  return { status: "unknown", source: SOURCE, models: [], error: error ? String(error) : null };
+}
+
+/**
+ * Strips the spinner's ANSI control codes and non-model lines (loading
+ * status, the "Available models" header, the trailing "Tip: ..." line),
+ * returning either an empty array (the account has no models — a real,
+ * confirmed answer) or the real `{id, displayName}` models — the same
+ * shape codex-models.js/claude-models.js already use, so callers never
+ * need to branch on catalog source.
+ */
+export function parseCursorModelsOutput(raw) {
+  const clean = String(raw ?? "").replace(ANSI_PATTERN, "");
+  const lines = clean.split("\n").map((line) => line.trim()).filter(Boolean).filter((line) => !LOADING_LINE.test(line));
+  if (lines.some((line) => NO_MODELS_SENTINEL.test(line))) return [];
+  const models = [];
+  for (const line of lines) {
+    const match = line.match(MODEL_LINE_PATTERN);
+    if (match) models.push({ id: match[1], displayName: match[2].trim() });
+  }
+  return models;
+}
+
+/**
+ * Reads Cursor Agent's real, currently-available model list for this
+ * account. `status: "measured"` with an empty `models` array is itself a
+ * real answer (this account has none) — distinct from `"unknown"`, which
+ * means the read itself failed.
+ */
+export async function readCursorModels({
+  spawn = defaultSpawn,
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+} = {}) {
+  let child;
+  try {
+    child = spawn("cursor-agent", ["models"], { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+  } catch (error) {
+    return unknown(error?.message ?? error);
+  }
+
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let finished = false;
+    const timer = setTimeout(() => finish(unknown("cursor-agent models timed out")), timeoutMs);
+
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearTimeout(timer);
+      try { child.kill?.(); } catch { /* best effort */ }
+      resolve(result);
+    }
+
+    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.stderr?.on("data", (chunk) => { stderr += chunk; });
+    child.once?.("error", (error) => finish(unknown(error?.message ?? error)));
+    child.once?.("close", (code, signal) => {
+      // A crash (killed by a signal, e.g. a real SIGSEGV) or a non-zero
+      // exit must never be silently reinterpreted as a clean, real
+      // "no models" answer — an empty/partial stdout from a crash mid-run
+      // parses identically to a genuine empty catalog, so exit status is
+      // the only real signal that tells them apart. Only a clean exit
+      // (code 0, no signal) is trusted to mean the CLI actually finished
+      // and its stdout is a real, complete answer.
+      if (signal) return finish(unknown(`cursor-agent models was killed by signal ${signal}${stderr ? `: ${stderr.trim()}` : ""}`));
+      if (code !== 0) return finish(unknown(`cursor-agent models exited with code ${code}${stderr ? `: ${stderr.trim()}` : ""}`));
+      finish({ status: "measured", source: SOURCE, models: parseCursorModelsOutput(stdout), error: null });
+    });
+  });
+}

package/src/global/observability/gentle-probe.js

@@ -7,8 +7,15 @@ import {
 import { normalizeProbeResult } from "./probe-contract.js";
 
 export const SUPPORTED_PROTOCOL = Object.freeze({ major: 2, minor: 0 });
+export const SUPPORTED_PROTOCOL_MINORS = Object.freeze([0, 1]);
 export const SUPPORTED_SCHEMA = "gentle-ai.review-integration.capabilities/v2";
+export const SUPPORTED_SCHEMA_V21 = "gentle-ai.review-integration.capabilities/v2.1";
+export const SUPPORTED_CAPABILITY_SCHEMAS = Object.freeze([
+  SUPPORTED_SCHEMA,
+  SUPPORTED_SCHEMA_V21
+]);
 export const SUPPORTED_CONTRACT = "gentle-ai.review-integration/v2";
+export const ADDITIVE_MINOR_POLICY = "optional-fields-only";
 export const SUPPORTED_MANDATORY_FEATURES = Object.freeze([
   "compact_v2_authority", "exact_receipt_replay", "five_delivery_gates",
   "immutable_snapshot", "legacy_v1_target_scoped_read_only",
@@ -51,7 +58,7 @@ export function evaluateGentleCapabilities(payload) {
       diagnostics: ["Capabilities payload is not an object."]
     });
   }
-  if (payload.schema !== SUPPORTED_SCHEMA) {
+  if (!SUPPORTED_CAPABILITY_SCHEMAS.includes(payload.schema)) {
     diagnostics.push(`schema mismatch: got ${String(payload.schema)}`);
   }
   if (payload.contract !== SUPPORTED_CONTRACT) {
@@ -60,9 +67,30 @@ export function evaluateGentleCapabilities(payload) {
   if (payload.protocol?.major !== SUPPORTED_PROTOCOL.major) {
     diagnostics.push(`protocol.major mismatch: got ${String(payload.protocol?.major)}`);
   }
-  if (payload.protocol?.minor !== SUPPORTED_PROTOCOL.minor) {
+  if (!SUPPORTED_PROTOCOL_MINORS.includes(payload.protocol?.minor)) {
     diagnostics.push(`protocol.minor mismatch: got ${String(payload.protocol?.minor)}`);
   }
+  const additivePolicy = payload.compatibility?.additive_minor_policy;
+  if (additivePolicy != null && additivePolicy !== ADDITIVE_MINOR_POLICY) {
+    diagnostics.push(`additive_minor_policy mismatch: got ${String(additivePolicy)}`);
+  }
+  if (typeof payload.bootstrap?.command === "string" && payload.bootstrap.command) {
+    evidence.push({
+      kind: "bootstrap",
+      command: payload.bootstrap.command,
+      required_feature: payload.bootstrap.required_feature ?? null
+    });
+  }
+  const requiredFeature = payload.bootstrap?.required_feature;
+  if (typeof requiredFeature === "string" && requiredFeature) {
+    const named = [
+      ...(Array.isArray(payload.features?.mandatory) ? payload.features.mandatory : []),
+      ...(Array.isArray(payload.features?.optional) ? payload.features.optional : [])
+    ];
+    if (!named.some((feature) => feature?.name === requiredFeature && feature.supported === true)) {
+      diagnostics.push(`bootstrap required_feature not supported: ${requiredFeature}`);
+    }
+  }
   const mandatory = payload.features?.mandatory;
   if (!Array.isArray(mandatory)) {
     diagnostics.push("features.mandatory must be an array.");

package/src/global/observability/huggingface-leaderboard.js

@@ -0,0 +1,97 @@
+// Real per-benchmark leaderboard data from Hugging Face's official Datasets
+// API — verified live against https://huggingface.co/api/datasets/{id}/leaderboard
+// (public, no API key needed for a public benchmark dataset). One dataset
+// covers exactly one benchmark (e.g. cais/hle for HLE, Idavidrein/gpqa for
+// GPQA); there is no cross-benchmark aggregate endpoint here. Fails closed
+// like every other observability probe: a failed fetch never fabricates a
+// result, it falls back to the last successfully cached snapshot (marked
+// "cached", with its real age) or "unknown" if there's no cache either.
+
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+
+export const SOURCE = "huggingface datasets api (leaderboard)";
+const DEFAULT_TIMEOUT_MS = 8000;
+
+function apiUrl(datasetId) {
+  return `https://huggingface.co/api/datasets/${datasetId}/leaderboard`;
+}
+
+function normalizeEntry(entry) {
+  return {
+    modelId: entry.modelId ?? null,
+    value: typeof entry.value === "number" ? entry.value : null,
+    rank: entry.rank ?? null,
+    verified: entry.verified === true,
+    notes: entry.notes ?? null
+  };
+}
+
+function ageLabel(fetchedAtIso) {
+  const fetchedAt = new Date(fetchedAtIso ?? "").getTime();
+  if (!Number.isFinite(fetchedAt)) return null;
+  const hours = (Date.now() - fetchedAt) / 3_600_000;
+  if (hours < 1) return "<1h";
+  if (hours < 48) return `${Math.round(hours)}h`;
+  return `${Math.round(hours / 24)}d`;
+}
+
+async function readAllCaches(homeDir, deps) {
+  const read = deps.readFile ?? readFile;
+  try {
+    const raw = await read(harnessHomePaths(homeDir).huggingfaceLeaderboardPath, "utf8");
+    const doc = JSON.parse(raw);
+    return doc && typeof doc === "object" ? doc : {};
+  } catch {
+    return {};
+  }
+}
+
+async function writeCache(homeDir, datasetId, snapshot, deps) {
+  const mkdirImpl = deps.mkdir ?? mkdir;
+  const writeJson = deps.writeAtomicJson ?? writeAtomicJson;
+  const path = harnessHomePaths(homeDir).huggingfaceLeaderboardPath;
+  const all = await readAllCaches(homeDir, deps);
+  all[datasetId] = snapshot;
+  await mkdirImpl(dirname(path), { recursive: true });
+  await writeJson(path, all);
+}
+
+function fromCache(cache, error) {
+  if (!cache || !Array.isArray(cache.entries) || typeof cache.fetchedAt !== "string") {
+    return { status: "unknown", source: SOURCE, fetchedAt: null, age: null, entries: [], error };
+  }
+  return { status: "cached", source: SOURCE, fetchedAt: cache.fetchedAt, age: ageLabel(cache.fetchedAt), entries: cache.entries, error };
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.datasetId - e.g. "cais/hle", "SWE-bench/SWE-bench_Verified", "Idavidrein/gpqa"
+ * @param {string} options.homeDir - required; the cache lives under this harness home
+ * @param {typeof fetch} [options.fetchImpl]
+ * @param {number} [options.timeoutMs]
+ */
+export async function readHuggingFaceLeaderboard({
+  datasetId, homeDir, fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS, ...deps
+} = {}) {
+  if (!datasetId) return { status: "unknown", source: SOURCE, fetchedAt: null, age: null, entries: [], error: "datasetId is required" };
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(apiUrl(datasetId), { signal: controller.signal });
+    if (!response.ok) throw new Error(`huggingface leaderboard api returned ${response.status}`);
+    const payload = await response.json();
+    const entries = Array.isArray(payload) ? payload.map(normalizeEntry) : [];
+    const fetchedAt = new Date().toISOString();
+    await writeCache(homeDir, datasetId, { fetchedAt, entries }, deps).catch(() => {});
+    return { status: "live", source: SOURCE, fetchedAt, age: "<1h", entries, error: null };
+  } catch (error) {
+    const all = await readAllCaches(homeDir, deps);
+    return fromCache(all[datasetId], error?.message ?? String(error));
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/global/observability/index.js

@@ -24,7 +24,8 @@ export {
   runPassiveObservabilitySnapshot
 } from "./passive-snapshot-flight.js";
 export {
-  SUPPORTED_PROTOCOL, SUPPORTED_SCHEMA, SUPPORTED_CONTRACT,
+  SUPPORTED_PROTOCOL, SUPPORTED_PROTOCOL_MINORS, SUPPORTED_SCHEMA, SUPPORTED_SCHEMA_V21,
+  SUPPORTED_CAPABILITY_SCHEMAS, SUPPORTED_CONTRACT, ADDITIVE_MINOR_POLICY,
   SUPPORTED_MANDATORY_FEATURES, evaluateGentleCapabilities, probeGentle, createGentleProbe,
   resolveGentleBinaryPath
 } from "./gentle-probe.js";