@kal-elsam/kairo-runtime 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.18.0 — 2026-09-18 (Kairo Runtime)
+
+Minor release. Provider visibility and quota-aware improvements to the
+`/project` PROJECT TEAM view.
+
+### Added
+
+- The PROJECT TEAM view (dashboard panel and `/project` overlay) now
+  shows the real provider alongside each role's model
+  (`CockpitView.teamRoleLabel()`), so it's clear which subscription
+  actually serves each role.
+- `/project cursor exhausted|available` — a manual, human-reported
+  toggle for Cursor's quota state, persisted through the same
+  per-provider usage store Codex/Claude/OpenCode Go already use. Cursor
+  exposes no real, zero-cost local usage/billing read, so this is the
+  one honest signal Kairo can act on; an exhausted Cursor is excluded
+  from team recommendations until cleared.
+- An early "LOW" warning tag (`LOW_QUOTA_WARN_PERCENT`, 20% remaining)
+  for Codex/Claude/OpenCode Go quota windows, shown in the compact usage
+  bar and `/usage`, strictly before the existing 5% hard-exclusion
+  threshold takes effect.
+
+### Fixed
+
+- The `/project` overlay's modal frame now uses a distinct,
+  high-contrast border instead of sharing the dashboard card's
+  low-contrast outline, and compacted its per-line spacing so a full
+  six-role team stays within the overlay's height budget.
+
 ## 0.17.0 — 2026-09-17 (Kairo Runtime)
 
 Minor release. Execution-worktree isolation (real git worktrees, per-role

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.17.0",
+  "version": "0.18.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

@@ -230,7 +230,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 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) · /why eligibility detail · /clear · /quit");
       } else if (command === "/usage") {
         for (const line of view.usageLines()) pushTranscript("kairo", line);
       } else if (command === "/providers") {
@@ -343,8 +343,26 @@ export async function runCockpitApp({
             const result = await service.refreshProjectStrategy({ cwd });
             pushTranscript("kairo", result ? `Project strategy is now ${result.status.toUpperCase()}.` : "Nothing to refresh yet — use /project analyze first.");
           }).finally(() => { editor.disableSubmit = false; });
+        } else if (sub === "cursor") {
+          // Cursor exposes no real, zero-cost local usage read (see
+          // execution-router.js's checkCandidate doc) — this manual toggle
+          // is the only way Kairo learns its quota state, ever. Never
+          // auto-detected, never inferred from a failed run.
+          const state = args[1]?.toLowerCase();
+          if (state !== "exhausted" && state !== "available") {
+            pushTranscript("kairo", "Usage: /project cursor exhausted|available");
+            editor.setText("");
+            return;
+          }
+          editor.setText("");
+          return runAction(`Marking Cursor ${state}`, async () => {
+            await service.setCursorManualQuota({ exhausted: state === "exhausted" });
+            pushTranscript("kairo", state === "exhausted"
+              ? "Cursor marked out of credits — excluded from team suggestions until you run /project cursor available."
+              : "Cursor marked available again — back in team suggestions.");
+          });
         } else {
-          pushTranscript("kairo", "Usage: /project status|analyze|analyst quality|efficient [--confirm]|approve|refresh");
+          pushTranscript("kairo", "Usage: /project status|analyze|analyst quality|efficient [--confirm]|approve|refresh|cursor exhausted|available");
         }
       } else if (command === "/plan") {
         const planTask = task.slice(command.length).trim();

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

@@ -33,6 +33,13 @@ export const PROJECT_OVERLAY_STATE = {
 
 const S = PROJECT_OVERLAY_STATE;
 
+// Give the modal frame a distinct, high-contrast outline without changing
+// the shared dashboard-card palette or the semantic state color of its rail.
+const overlayFrameTheme = {
+  ...theme,
+  fg: (role, text) => theme.fg(role === "border" ? "info" : role, text)
+};
+
 function teamLines(label, team, aiTeamLabel, tone = "bold") {
   const lines = [tone === "bold" ? theme.bold(label) : theme.fg("muted", label)];
   if (!team?.length) {
@@ -263,7 +270,7 @@ export class ProjectOverlay {
   buildResultRoleList() {
     const team = this.suggestedStrategy?.projectTeam ?? [];
     const items = team.map((entry) => {
-      const modelText = entry.model ? this.view.aiTeamLabel(entry.model) : "no eligible option";
+      const modelText = entry.model ? this.view.teamRoleLabel(entry.model) : "no eligible option";
       const overrideNote = entry.assignmentSource === "override" ? theme.fg("accent", " (override)") : "";
       // Role + model are the real primary information here — explicit
       // `text` color, never left to default/muted.
@@ -526,8 +533,11 @@ export class ProjectOverlay {
     // isn't a modal boundary a human eye reliably notices.
     const box = new Box(2, 1);
     this.box = box;
-    const aiTeamLabel = (model) => this.view.aiTeamLabel(model);
-    const push = (text) => box.addChild(new Text(text));
+    const aiTeamLabel = (model) => this.view.teamRoleLabel(model);
+    // Text defaults to one blank row above and below every child; inside
+    // a framed modal that inflated the height until pi-tui clipped the
+    // bottom border. Keep spacing explicit and compact instead.
+    const push = (text) => box.addChild(new Text(text, 0, 0));
     // The real, ticking spinner+elapsed-time line every other in-flight
     // action in the cockpit already uses (view.beginAction/tickSpinner/
     // actionStatusLine — app.js's own fast timer keeps it live) — never a
@@ -655,7 +665,7 @@ export class ProjectOverlay {
         break;
     }
     const innerWidth = cardInnerWidth(width);
-    return renderPanel("Project", this.panelTone(), theme, width, box.render(innerWidth));
+    return renderPanel("Project", this.panelTone(), overlayFrameTheme, width, box.render(innerWidth));
   }
 }
 

package/src/global/cockpit/view.js

@@ -2,6 +2,22 @@ import { matchesKey, Key, truncateToWidth, visibleWidth, wrapTextWithAnsi } from
 import { buildTaskRows, clampSelection, isActionAvailable } from "./rows.js";
 import { CARD_TONE, cardBottom, cardInnerWidth, cardLine, cardTop, renderPanel as renderPanelWithTheme } from "./card.js";
 import { theme } from "./theme.js";
+import { LOW_QUOTA_WARN_PERCENT } from "../intelligence/execution-router.js";
+
+/**
+ * A real, early heads-up — never fabricated, never re-deriving its own
+ * threshold (see execution-router.js's LOW_QUOTA_WARN_PERCENT, the same
+ * canonical policy checkCandidate itself uses for its harder exclusion
+ * cutoff). `alreadyFlagged` skips this for a window a caller already
+ * tagged some other way (e.g. Go's own "RATE LIMITED"), so a single
+ * window is never double-tagged.
+ * @param {number|null|undefined} remainingPercent
+ * @param {boolean} [alreadyFlagged]
+ */
+function quotaWarnSuffix(remainingPercent, alreadyFlagged = false) {
+  if (alreadyFlagged || remainingPercent == null) return "";
+  return remainingPercent < LOW_QUOTA_WARN_PERCENT ? " LOW" : "";
+}
 
 /** view.js's own local binding for card.js's real renderPanel, fixed to this module's theme. */
 function renderPanel(title, tone, width, contentLines, targetLineCount = contentLines.length) {
@@ -560,8 +576,8 @@ export class CockpitView {
       };
     }
     const lines = [];
-    if (strategy.bootstrapAnalyst) lines.push(`${"Project Analyst".padEnd(18)} ${this.aiTeamLabel(strategy.bootstrapAnalyst)}`);
-    if (strategy.orchestrator) lines.push(`${"Orchestrator".padEnd(18)} ${this.aiTeamLabel(strategy.orchestrator)}`);
+    if (strategy.bootstrapAnalyst) lines.push(`${"Project Analyst".padEnd(18)} ${this.teamRoleLabel(strategy.bootstrapAnalyst)}`);
+    if (strategy.orchestrator) lines.push(`${"Orchestrator".padEnd(18)} ${this.teamRoleLabel(strategy.orchestrator)}`);
     // The real OPERATIONAL team (see buildProjectStrategy's own doc) —
     // never qualityTeam, which is comparative reference only. The overlay
     // (project-overlay.js) already shows projectTeam under this exact
@@ -570,7 +586,7 @@ export class CockpitView {
     // remains as a fallback for a strategy persisted before projectTeam
     // existed (see applyProjectTeamOverride's own legacy-entry comment).
     for (const entry of strategy.projectTeam ?? strategy.qualityTeam ?? []) {
-      lines.push(`${entry.role.padEnd(18)} ${entry.model ? this.aiTeamLabel(entry.model) : theme.fg("warning", "no eligible option")}`);
+      lines.push(`${entry.role.padEnd(18)} ${entry.model ? this.teamRoleLabel(entry.model) : theme.fg("warning", "no eligible option")}`);
     }
     if (strategy.status === "suggested") lines.push(theme.fg("muted", "Suggested from real project analysis. Use /project approve to activate."));
     if (strategy.status === "stale") lines.push(theme.fg("warning", "Real evidence changed since approval — use /project refresh."));
@@ -741,6 +757,19 @@ export class CockpitView {
     return `${provider} · ${raw}`;
   }
 
+  /**
+   * Role -> model -> provider, for the PROJECT TEAM listing specifically:
+   * keeps aiTeamLabel()'s cleaned modelName (unlike aiTeamLabelWithProvider's
+   * raw/technical variant) but still names the real adapter each role would
+   * actually run against — two roles can land on visually similar model
+   * names from different providers, and knowing which subscription a role
+   * draws from is exactly what a real, provider-aware team review needs.
+   */
+  teamRoleLabel(model) {
+    const provider = model.adapterId.charAt(0).toUpperCase() + model.adapterId.slice(1);
+    return `${this.aiTeamLabel(model)}  ·  ${provider}`;
+  }
+
   /**
    * The global "AI TEAM" widget: one line per role (Explorer / Architect /
    * Builder / Debugger / Tester / Reviewer) naming only the
@@ -1155,17 +1184,20 @@ export class CockpitView {
 
     const codex = usage.codex;
     const codexText = codex?.primary
-      ? `Codex 5h ${codex.primary.remainingPercent}%${codex.secondary ? ` / W ${codex.secondary.remainingPercent}%` : ""}`
+      ? `Codex 5h ${codex.primary.remainingPercent}%${quotaWarnSuffix(codex.primary.remainingPercent)}${codex.secondary ? ` / W ${codex.secondary.remainingPercent}%${quotaWarnSuffix(codex.secondary.remainingPercent)}` : ""}`
       : `Codex ${status("Codex") ?? "usage unknown"}`;
 
     const claude = usage.claude;
     const claudeText = claude?.primary
-      ? `Claude S ${claude.primary.remainingPercent}%${claude.secondary ? ` / W ${claude.secondary.remainingPercent}%` : ""}`
+      ? `Claude S ${claude.primary.remainingPercent}%${quotaWarnSuffix(claude.primary.remainingPercent)}${claude.secondary ? ` / W ${claude.secondary.remainingPercent}%${quotaWarnSuffix(claude.secondary.remainingPercent)}` : ""}`
       : `Claude ${status("Claude") ?? "usage unknown"}`;
 
     const go = usage.opencode?.go;
     const goText = go?.windows?.length
-      ? `Go ${go.windows.map((window) => `${window.remainingPercent}%${window.status === "rate-limited" ? " LIMITED" : ""}`).join(" / ")}`
+      ? `Go ${go.windows.map((window) => {
+        const limited = window.status === "rate-limited";
+        return `${window.remainingPercent}%${limited ? " LIMITED" : quotaWarnSuffix(window.remainingPercent)}`;
+      }).join(" / ")}`
       : `Go ${status("OpenCode") ?? "usage unknown"}`;
 
     const header = `KAIRO · ${project}`;
@@ -1232,15 +1264,18 @@ export class CockpitView {
     const lines = [];
     const codex = usage.codex;
     lines.push(codex?.windows?.length
-      ? `Codex ${codex.windows.map((window) => `${window.name} ${window.remainingPercent}% left${window.resetsAtIso ? ` reset ${window.resetsAtIso}` : ""}`).join(" · ")} · source: ${codex.source ?? "measured"}`
+      ? `Codex ${codex.windows.map((window) => `${window.name} ${window.remainingPercent}% left${quotaWarnSuffix(window.remainingPercent)}${window.resetsAtIso ? ` reset ${window.resetsAtIso}` : ""}`).join(" · ")} · source: ${codex.source ?? "measured"}`
       : "Codex usage unknown · source: Codex app-server · no quota fabricated");
     const claude = usage.claude;
     lines.push(claude?.windows?.length
-      ? `Claude ${claude.windows.map((window) => `${window.label ?? window.name} ${window.remainingPercent}% left`).join(" · ")} · source: ${claude.source ?? "measured"}`
+      ? `Claude ${claude.windows.map((window) => `${window.label ?? window.name} ${window.remainingPercent}% left${quotaWarnSuffix(window.remainingPercent)}`).join(" · ")} · source: ${claude.source ?? "measured"}`
       : "Claude usage unknown · no quota fabricated");
     const go = usage.opencode?.go;
     lines.push(go?.windows?.length
-      ? `Go ${go.windows.map((window) => `${shortWindowName(window.name)} ${window.remainingPercent}%${window.status === "rate-limited" ? " RATE LIMITED" : ""}`).join(" · ")} · source: ${go.source ?? "measured"}`
+      ? `Go ${go.windows.map((window) => {
+        const limited = window.status === "rate-limited";
+        return `${shortWindowName(window.name)} ${window.remainingPercent}%${limited ? " RATE LIMITED" : quotaWarnSuffix(window.remainingPercent)}`;
+      }).join(" · ")} · source: ${go.source ?? "measured"}`
       : "Go usage unknown · source unavailable");
     return lines;
   }

package/src/global/conversation/service.js

@@ -35,6 +35,7 @@ import { runCodexSandboxedBootstrap } from "./codex-sandbox.js";
 import { createBootstrapAnalyzerAdapter } from "./bootstrap-analyzer-adapters.js";
 import { verifyClaudeSubscriptionAuth } from "../runtime/execution-adapters/claude.js";
 import { readProjectStrategy, writeProjectStrategy } from "./project-strategy-store.js";
+import { readProviderUsage, writeProviderUsage } from "../runtime/usage-store.js";
 import { resolveProjectRoute } from "./project-router.js";
 import { readArtificialAnalysisModels } from "../observability/artificial-analysis-models.js";
 import { readHuggingFaceLeaderboard } from "../observability/huggingface-leaderboard.js";
@@ -269,6 +270,8 @@ export function createConversationService(deps = {}) {
   const computeProjectProfileImpl = deps.computeProjectProfile ?? computeProjectProfile;
   const readProjectStrategyImpl = deps.readProjectStrategy ?? readProjectStrategy;
   const writeProjectStrategyImpl = deps.writeProjectStrategy ?? writeProjectStrategy;
+  const readProviderUsageImpl = deps.readProviderUsage ?? readProviderUsage;
+  const writeProviderUsageImpl = deps.writeProviderUsage ?? writeProviderUsage;
   const parseProjectAnalysisImpl = deps.parseProjectAnalysis ?? parseProjectAnalysis;
   const deriveRoleRequirementsImpl = deps.deriveRoleRequirements ?? deriveRoleRequirements;
   const buildSanitizedSnapshotImpl = deps.buildSanitizedSnapshot ?? buildSanitizedSnapshot;
@@ -446,10 +449,15 @@ export function createConversationService(deps = {}) {
         // launchable), so Kairo never actually picks Go for a real run
         // it's guaranteed to reject at launch. Zen and Cursor stay
         // excluded here regardless (PAYG risk / manual-only).
+        // Cursor's own real usage/billing data is never auto-detected (see
+        // execution-router.js's checkCandidate doc) — this is only ever
+        // the human's last word via /project cursor exhausted|available,
+        // persisted as an ordinary provider usage record.
+        const cursorManualQuota = await readProviderUsageImpl(homeDir, "cursor");
         const eligibility = {};
         const candidates = [];
         for (const adapterId of ["codex", "claude", "opencode-go", "opencode-zen", "cursor"]) {
-          const check = checkCandidate(adapterId, { adapters, codexUsage, claudeUsage, opencodeGoUsage: opencodeUsage?.go }, { requireLaunchable: false });
+          const check = checkCandidate(adapterId, { adapters, codexUsage, claudeUsage, opencodeGoUsage: opencodeUsage?.go, cursorManualQuota }, { requireLaunchable: false });
           eligibility[adapterId] = check;
           if (check.ok) candidates.push(adapterId);
         }
@@ -815,6 +823,25 @@ export function createConversationService(deps = {}) {
       }
       return { ...existing, projectRoot, profile };
     },
+    /**
+     * `/project cursor exhausted|available`: the ONLY way Cursor's quota
+     * state ever changes (see execution-router.js's checkCandidate doc —
+     * Cursor exposes no real, zero-cost local usage read, so this is never
+     * auto-detected). Persisted as an ordinary provider usage record
+     * (runtime/usage-store.js), read back by snapshot()'s own eligibility
+     * computation on every poll — never held only in memory, so it
+     * survives a restart the same way a real detected quota state would.
+     * @param {{exhausted: boolean, reason?: string|null}} args
+     */
+    async setCursorManualQuota({ exhausted, reason = null }) {
+      const record = {
+        provider: "cursor", manualExhausted: !!exhausted,
+        reason: exhausted ? (reason ?? "Cursor marked out of credits (manual, via /project cursor exhausted)") : null,
+        setAt: new Date().toISOString()
+      };
+      await writeProviderUsageImpl(homeDir, "cursor", record);
+      return record;
+    },
     /**
      * The real projectTeam edit catalog for one role (section 4 —
      * "Edición persistida del PROJECT TEAM") — every real, non-superseded

package/src/global/intelligence/execution-router.js

@@ -126,7 +126,13 @@ function remainingPercent(usageEntry) {
 // Below this real remaining-quota percentage, a provider is treated as
 // exhausted for automatic routing — conserved for the tests explicitly
 // listed as this increment's scope, not a newly-invented number.
-const MIN_QUOTA_PERCENT = 5;
+export const MIN_QUOTA_PERCENT = 5;
+
+// A softer, earlier heads-up threshold — strictly above MIN_QUOTA_PERCENT,
+// so the human sees a warning before a provider actually gets excluded,
+// never after. Display-only: it never affects checkCandidate's own
+// eligibility verdict (see CockpitView's own status-bar consumer).
+export const LOW_QUOTA_WARN_PERCENT = 20;
 
 /**
  * The single eligibility policy shared by execution routing, ask routing,
@@ -135,7 +141,14 @@ const MIN_QUOTA_PERCENT = 5;
  * Real availability/launchability/quota only; never a capability judgment
  * (that's scoreAvailableModels' job, applied only to survivors of this).
  * @param {string} adapterId - "codex" | "claude" | "opencode-go" | "opencode-zen" | "cursor"
- * @param {{adapters: object[], codexUsage?: object|null, claudeUsage?: object|null, opencodeGoUsage?: object|null}} context
+ * @param {{adapters: object[], codexUsage?: object|null, claudeUsage?: object|null, opencodeGoUsage?: object|null, cursorManualQuota?: {manualExhausted: boolean, reason?: string|null}|null}} context -
+ *   `cursorManualQuota` is the human-reported override (see
+ *   runtime/usage-store.js's `cursor.json` record, set via
+ *   `/project cursor exhausted|available`) — Cursor exposes no real,
+ *   zero-cost local quota read (its CLI has no usage/billing subcommand
+ *   and a successful `-p` call only reports per-request token counts, not
+ *   remaining account balance), so unlike Codex/Claude/OpenCode Go this is
+ *   never auto-detected, only ever what the human last told Kairo.
  * @returns {{ok: boolean, reason: string|null}}
  * @param {{requireLaunchable?: boolean}} [options] - `requireLaunchable: false`
  *   is for AI TEAM's recommendation surface only (service.js's snapshot()):
@@ -151,7 +164,7 @@ const MIN_QUOTA_PERCENT = 5;
  *   uses the default `true` — it must never pick something guaranteed to
  *   fail at launch (run-manager.js's own launchable gate would reject it).
  */
-export function checkCandidate(adapterId, { adapters, codexUsage, claudeUsage, opencodeGoUsage }, { requireLaunchable = true } = {}) {
+export function checkCandidate(adapterId, { adapters, codexUsage, claudeUsage, opencodeGoUsage, cursorManualQuota }, { requireLaunchable = true } = {}) {
   // Zen carries real PAYG/billing risk (see conversation/service.js's
   // capabilities.openCodeExecution) — never an automatic pick, regardless
   // of what its real catalog/benchmarks might otherwise say.
@@ -195,6 +208,15 @@ export function checkCandidate(adapterId, { adapters, codexUsage, claudeUsage, o
     const limited = windows.find((window) => window.status === "rate-limited");
     if (limited) return { ok: false, reason: `OpenCode Go ${limited.name} window is rate-limited` };
   }
+  // Cursor: only ever the human's own last word (see this function's own
+  // doc) — never fabricated from a guess. Checked here, after the
+  // requireLaunchable-gated manual-only return above, so it only ever
+  // takes effect on the recommendation path (requireLaunchable: false) —
+  // real task routing already refuses Cursor unconditionally regardless
+  // of quota.
+  if (adapterId === "cursor" && cursorManualQuota?.manualExhausted) {
+    return { ok: false, reason: cursorManualQuota.reason ?? "Cursor marked out of credits (manual, via /project cursor exhausted)" };
+  }
   return { ok: true, reason: null };
 }
 

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.17.0" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.18.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.17.0" },
+      clientInfo: { name: "kairo", title: "Kairo", version: "0.18.0" },
       capabilities: {}
     });
   });