@kal-elsam/kairo-runtime 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.28.0 — 2026-09-19 (Kairo Runtime)
+
+Minor release. `/models --verify-access` verifies Claude model entitlement on demand.
+
+### Added
+
+- `/models --verify-access [--refresh]` — sequential, human-triggered Claude
+  entitlement probes with a real cost statement before any spawn. Without
+  `--refresh`, only unverified or TTL-expired models are probed; an all-
+  unverified sweep does not persist evidence.
+- One-line Spanish preflight notice when Claude models still have unverified
+  access (recommendable, never auto-launched).
+
 ## 0.27.0 — 2026-09-19 (Kairo Runtime)
 
 Minor release. Claude model entitlement now gates PROJECT TEAM pools and routes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Pi, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",

package/src/global/cockpit/app.js

@@ -258,7 +258,7 @@ export async function runCockpitApp({
       // blocks with no indication of which command produced which one.
       pushTranscript("user", task);
       if (command === "/help") {
-        pushTranscript("kairo", "Shift+Tab cycles ASK/PLAN/AGENT · /project interactive overlay (or analyze/analyst/approve/refresh/status/cursor exhausted|available subcommands for scripted use) · /plan <task> force a plan · /usage automatic-provider status (Codex/Claude/Go) · /providers all connections incl. Zen/Cursor (manual) · /models CAPABILITY + EFFICIENT picks (--evidence for raw metrics) · /why eligibility detail · /clear · /quit");
+        pushTranscript("kairo", "Shift+Tab cycles ASK/PLAN/AGENT · /project interactive overlay (or analyze/analyst/approve/refresh/status/cursor exhausted|available subcommands for scripted use) · /plan <task> force a plan · /usage automatic-provider status (Codex/Claude/Go) · /providers all connections incl. Zen/Cursor (manual) · /models CAPABILITY + EFFICIENT picks (--evidence for raw metrics; --verify-access [--refresh] for Claude entitlement) · /why eligibility detail · /clear · /quit");
       } else if (command === "/usage") {
         for (const line of view.usageLines()) pushTranscript("kairo", line);
       } else if (command === "/providers") {
@@ -271,8 +271,38 @@ export async function runCockpitApp({
         // the plain-language why (capability, efficient alternative,
         // fallback), never raw metrics/percentages/ids/sources. Those
         // stay behind the explicit --evidence flag for technical audit.
-        const flag = task.slice(command.length).trim();
-        const explainLines = flag === "--evidence" ? view.aiTeamDetailLines() : view.modelsExplainLines();
+        // --verify-access [--refresh] is the only path that spawns Claude
+        // entitlement probes (never on snapshot / first poll).
+        const flags = new Set(task.slice(command.length).trim().split(/\s+/).filter(Boolean));
+        if (flags.has("--verify-access")) {
+          const refresh = flags.has("--refresh");
+          editor.disableSubmit = true;
+          editor.setText("");
+          return runAction("Verifying Claude model access", async () => {
+            const summary = await service.verifyClaudeEntitlements({
+              cwd,
+              refresh,
+              beforeProbe: ({ costStatement }) => {
+                pushTranscript("kairo", costStatement);
+              },
+              onProgress: ({ modelId, index, total }) => {
+                view.beginAction(`Verifying Claude access (${index + 1}/${total}): ${modelId}`);
+              }
+            });
+            const allowed = summary.results.filter((r) => r.status === "allowed").length;
+            const denied = summary.results.filter((r) => r.status === "denied").length;
+            const unverified = summary.results.filter((r) => r.status === "unverified").length;
+            if (summary.probed.length === 0) {
+              pushTranscript("kairo", "Claude access already verified for the current catalog (use --refresh to re-probe).");
+            } else {
+              pushTranscript(
+                "kairo",
+                `Claude access check: ${summary.probed.length} probed · ${allowed} allowed · ${denied} denied · ${unverified} unverified${summary.persisted ? " · cache updated" : " · cache unchanged"}.`
+              );
+            }
+          }).finally(() => { editor.disableSubmit = false; });
+        }
+        const explainLines = flags.has("--evidence") ? view.aiTeamDetailLines() : view.modelsExplainLines();
         for (const line of explainLines) pushTranscript("kairo", line);
       } else if (command === "/why") {
         // Drill-down for FIT: which providers were excluded and the exact
@@ -318,6 +348,9 @@ export async function runCockpitApp({
           return runAction("Analyzing project locally (read-only)", async () => {
             const preflight = await service.preflightProject({ cwd });
             view.pendingProjectAnalysis = preflight;
+            if (preflight.unverifiedClaudeNotice) {
+              pushTranscript("kairo", preflight.unverifiedClaudeNotice);
+            }
             if (!preflight.alternatives.length) {
               pushTranscript("kairo", "No real Project Analyst candidate is available right now (ASK only supports Codex/Claude today).");
               return;

package/src/global/cockpit/project-overlay.js

@@ -160,6 +160,9 @@ export class ProjectOverlay {
     this.view.beginAction("Reading project evidence locally");
     try {
       this.preflight = await this.service.preflightProject({ cwd: this.cwd });
+      if (this.preflight.unverifiedClaudeNotice) {
+        this.onNarrate?.(this.preflight.unverifiedClaudeNotice);
+      }
       const models = this.preflight.analystCatalog?.models ?? [];
       if (!models.length) {
         this.state = S.NO_ANALYST;

package/src/global/conversation/service.js

@@ -41,9 +41,15 @@ import { readArtificialAnalysisModels } from "../observability/artificial-analys
 import { readHuggingFaceLeaderboard } from "../observability/huggingface-leaderboard.js";
 import {
   DEFAULT_ENTITLEMENT_TTL_MS,
+  mergeEntitlementResults,
   readClaudeEntitlementCache,
-  resolveClaudeEntitlements
+  resolveClaudeEntitlements,
+  writeClaudeEntitlementCache
 } from "../observability/claude-entitlement-store.js";
+import {
+  ENTITLEMENT,
+  probeClaudeModelEntitlements
+} from "../observability/claude-model-entitlement.js";
 import {
   annotateWithRegistryEvidence, bestEfficientModelPerRoleGlobal, bestModelPerRole, bestModelPerRoleGlobal, buildAiTeam,
   buildEfficientTeam, scoreAvailableModels, summarizeCatalogCoverage
@@ -64,6 +70,35 @@ export const CONVERSATION_SCHEMA = "kairo.conversation/v1";
 // 30s default.
 const BOOTSTRAP_ANALYST_TIMEOUT_MS = 180_000;
 
+/** Max Claude entitlement probes per `/models --verify-access` sweep. */
+const CLAUDE_ENTITLEMENT_MAX_PROBES = 12;
+
+/**
+ * Cost statement printed before any Claude entitlement spawn. Economy is
+ * measured: denied probes cost $0; allowed ones about one cent each.
+ * @param {{ pendingCount?: number }} [options]
+ */
+export function buildClaudeEntitlementVerifyCostStatement({ pendingCount = 0 } = {}) {
+  const n = Math.max(0, Number(pendingCount) || 0);
+  if (n <= 0) {
+    return "No Claude models need access verification right now (denied probes cost $0; allowed ones about one cent each).";
+  }
+  return `About to verify ${n} Claude model${n === 1 ? "" : "s"}: models your plan denies cost $0; allowed ones cost about one cent each.`;
+}
+
+/**
+ * One-line preflight notice when unverified Claude models exist.
+ * @param {number} count
+ */
+export function buildUnverifiedClaudePreflightNotice(count) {
+  const n = Math.max(0, Number(count) || 0);
+  return `${n} modelos de Claude tienen acceso sin verificar — se pueden recomendar pero nunca lanzar automáticamente. Corré /models --verify-access para verificar (los que tu plan deniega cuestan $0; los permitidos, alrededor de un centavo cada uno).`;
+}
+
+function isPersistableEntitlementStatus(status) {
+  return status === ENTITLEMENT.ALLOWED || status === ENTITLEMENT.DENIED;
+}
+
 function publicPlan(record, execution = null) {
   const status = record.status ?? record;
   return {
@@ -352,6 +387,9 @@ export function createConversationService(deps = {}) {
   const readOpenCodeGoCached = createCachedProbe(readOpenCodeGoImpl, opencodeGoUsageTtlMs);
   const readOpenCodeStatsCached = createCachedProbe(readOpenCodeStatsImpl, opencodeUsageTtlMs);
   const readClaudeEntitlementCacheImpl = deps.readClaudeEntitlementCache ?? readClaudeEntitlementCache;
+  const writeClaudeEntitlementCacheImpl = deps.writeClaudeEntitlementCache ?? writeClaudeEntitlementCache;
+  const mergeEntitlementResultsImpl = deps.mergeEntitlementResults ?? mergeEntitlementResults;
+  const probeClaudeModelEntitlementsImpl = deps.probeClaudeModelEntitlements ?? probeClaudeModelEntitlements;
   const readClaudeEntitlementCacheCached = createCachedProbe(
     () => readClaudeEntitlementCacheImpl(homeDir), claudeEntitlementCacheTtlMs
   );
@@ -821,7 +859,92 @@ export function createConversationService(deps = {}) {
       const candidates = { scoredAll, eligibility, registry, providerCapacity, claudeEntitlement };
       const alternatives = computeBootstrapAnalystAlternatives(candidates);
       const analystCatalog = computeBootstrapAnalystCatalog({ ...candidates, unscoredModels });
-      return { profile, alternatives, candidates, analystCatalog, projectRoot };
+      const unverifiedCount = Object.values(claudeEntitlement).filter(
+        (entry) => entry?.status === ENTITLEMENT.UNVERIFIED
+      ).length;
+      const unverifiedClaudeNotice = unverifiedCount > 0
+        ? buildUnverifiedClaudePreflightNotice(unverifiedCount)
+        : null;
+      return { profile, alternatives, candidates, analystCatalog, projectRoot, unverifiedClaudeNotice };
+    },
+    /**
+     * `/models --verify-access [--refresh]`: the only service path that
+     * spawns `probeClaudeModelEntitlements`. Without refresh, only
+     * unverified / TTL-expired catalog ids are probed; with refresh, every
+     * catalog id is probed (still capped at maxProbes=12). Persist only when
+     * at least one allowed/denied result exists — an all-unverified sweep
+     * never invents evidence on disk.
+     *
+     * @param {object} args
+     * @param {string} args.cwd
+     * @param {boolean} [args.refresh]
+     * @param {(info: { pendingCount: number, pendingIds: string[], costStatement: string }) => (void|Promise<void>)} [args.beforeProbe]
+     *   Called after the probe set is known and BEFORE any spawn — app.js
+     *   prints the cost statement here.
+     * @param {(info: { modelId: string, index: number, total: number, result: object }) => void} [args.onProgress]
+     */
+    async verifyClaudeEntitlements({ cwd, refresh = false, beforeProbe = null, onProgress = null } = {}) {
+      const projectRoot = cwd ? await root(cwd) : null;
+      const catalog = readClaudeModelsImpl();
+      const catalogIds = (catalog.models ?? []).map((m) => m.id).filter(Boolean);
+      let auth = null;
+      try {
+        auth = await verifyClaudeSubscriptionAuthImpl({});
+      } catch {
+        auth = null;
+      }
+      const subscriptionType = auth?.subscriptionType ?? null;
+      const cache = await readClaudeEntitlementCacheImpl(homeDir);
+      const nowMs = now();
+      const ttlMs = deps.claudeEntitlementTtlMs ?? DEFAULT_ENTITLEMENT_TTL_MS;
+      const resolved = resolveClaudeEntitlements({
+        cache,
+        subscriptionType,
+        catalogIds,
+        now: nowMs,
+        ttlMs
+      });
+      const pendingIds = (refresh
+        ? catalogIds
+        : catalogIds.filter((id) => resolved[id]?.status === ENTITLEMENT.UNVERIFIED)
+      ).slice(0, CLAUDE_ENTITLEMENT_MAX_PROBES);
+      const costStatement = buildClaudeEntitlementVerifyCostStatement({ pendingCount: pendingIds.length });
+      if (typeof beforeProbe === "function") {
+        await beforeProbe({ pendingCount: pendingIds.length, pendingIds, costStatement });
+      }
+      if (pendingIds.length === 0) {
+        return {
+          probed: [],
+          results: [],
+          costStatement,
+          persisted: false,
+          pendingCount: 0,
+          refresh: Boolean(refresh),
+          subscriptionType
+        };
+      }
+      const results = await probeClaudeModelEntitlementsImpl({
+        modelIds: pendingIds,
+        maxProbes: CLAUDE_ENTITLEMENT_MAX_PROBES,
+        cwd: projectRoot ?? process.cwd(),
+        onProgress
+      });
+      const hasPersistable = results.some((result) => isPersistableEntitlementStatus(result?.status));
+      let persisted = false;
+      if (hasPersistable) {
+        const merged = mergeEntitlementResultsImpl(cache, { subscriptionType, results });
+        await writeClaudeEntitlementCacheImpl(homeDir, merged);
+        persisted = true;
+      }
+      return {
+        probed: pendingIds,
+        results,
+        costStatement,
+        persisted,
+        pendingCount: pendingIds.length,
+        refresh: Boolean(refresh),
+        subscriptionType
+      };
     },
     /**
      * `/project analyst quality|efficient --confirm` (ANALYZING -> SUGGESTED):

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

@@ -89,7 +89,7 @@ export async function readCodexModels({
     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.27.0" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.28.0" },
       capabilities: {}
     });
   });

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

@@ -151,7 +151,7 @@ export async function readCodexUsage({
     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.27.0" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.28.0" },
       capabilities: {}
     });
   });