@kal-elsam/kairo-runtime 0.23.1 → 0.24.0

package/CHANGELOG.md

@@ -5,6 +5,54 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.24.0 — 2026-09-18 (Kairo Runtime)
+
+Minor release. ASK mode joins PROJECT TEAM.
+
+### Changed
+
+- ASK mode now checks PROJECT TEAM's Explorer role first (read-only
+  investigation is exactly Explorer's job), via the same routing real
+  execution already uses — instead of always going through a fully
+  separate, generic quota/effort heuristic. Falls back to that
+  heuristic only when there's no active team yet, or Explorer's real
+  assignment isn't one ASK can actually invoke (Cursor/OpenCode
+  Go/Zen aren't ask-capable yet). Role is always Explorer, never
+  inferred from the question's text.
+
+### Fixed
+
+- A flaky timing test in `quick-ask.test.js` (from 0.23.2) used
+  margins too tight to reliably survive full-suite load; widened them.
+
+Not yet in this release: PLAN mode routing through the Orchestrator
+role (plan creation is currently structurally Codex-only, a bigger
+change than a routing choice), and AGENT mode (an open product
+question on whether it should skip the plan→approve gate).
+
+## 0.23.2 — 2026-09-18 (Kairo Runtime)
+
+Patch release.
+
+### Fixed
+
+- Routing eligibility (`checkCandidate`, shared by real execution
+  routing, ASK routing, and the FIT widget) and ASK's own ordering
+  only ever read the primary (5h) quota window — a provider whose
+  weekly window was nearly exhausted still got picked first and was
+  never excluded, as long as its 5h window looked healthy. Now takes
+  the worse of the two windows everywhere, fail-closed, matching the
+  same principle already applied to OpenCode Go's own windows.
+- `askCodex`/`askClaude` (the ASK-mode question path) used a fixed 30s
+  deadline from process start. Codex's ASK path always uses the
+  provider's single default model regardless of question complexity
+  (no effort-based tiering for Codex today), so a heavier default
+  model plus a cold sandboxed `codex exec` start can genuinely exceed
+  30s with real quota to spare — a real, slow answer, not a hang. Both
+  ask calls now reset their timeout on every real stdout/stderr chunk
+  instead, never an absolute one, so only a genuine hang still times
+  out.
+
 ## 0.23.1 — 2026-09-18 (Kairo Runtime)
 
 Patch release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.23.1",
+  "version": "0.24.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/conversation/project-strategy.js

@@ -23,8 +23,12 @@ import { computeRoleEvaluations } from "../intelligence/capability-scoring.js";
 // The Bootstrap Analyst investigates read-only via askProvider
 // (intelligence/quick-ask.js), which only actually supports these two
 // providers today — offering any other real candidate as an "alternative"
-// here would be a menu item Kairo can't actually run.
-const ASK_SUPPORTED_ADAPTERS = new Set(["codex", "claude"]);
+// here would be a menu item Kairo can't actually run. Exported: ASK mode's
+// own real-time routing (service.js's planAsk) needs this exact same real
+// constraint when it tries to route a plain question through a PROJECT
+// TEAM role — a role assigned to, say, opencode-go is a real, valid team
+// assignment, just not one askProvider can call.
+export const ASK_SUPPORTED_ADAPTERS = new Set(["codex", "claude"]);
 
 /**
  * The Bootstrap Analyst as a temporary, read-only WORKFLOW — deliberately

package/src/global/conversation/service.js

@@ -26,8 +26,8 @@ import { appendTranscriptEntry, clearTranscript, readTranscript } from "./transc
 import { readSession, writeSessionMode } from "./session-store.js";
 import { computeProjectProfile } from "./project-profile.js";
 import {
-  buildProjectStrategy, computeBootstrapAnalystAlternatives, computeBootstrapAnalystCatalog, isStrategyStale,
-  computeProjectTeamEditCatalog, applyProjectTeamOverride, resetProjectTeamAssignment
+  ASK_SUPPORTED_ADAPTERS, buildProjectStrategy, computeBootstrapAnalystAlternatives, computeBootstrapAnalystCatalog,
+  isStrategyStale, computeProjectTeamEditCatalog, applyProjectTeamOverride, resetProjectTeamAssignment
 } from "./project-strategy.js";
 import { buildAnalystPrompt, deriveRoleRequirements, parseProjectAnalysis } from "./project-analysis.js";
 import { buildSanitizedSnapshot } from "./sanitized-snapshot.js";
@@ -662,6 +662,34 @@ export function createConversationService(deps = {}) {
      */
     async planAsk({ cwd, task }) {
       const projectRoot = await root(cwd);
+      // PROJECT TEAM's own Explorer role first — a real, approved,
+      // project-specific assignment beats the generic heuristic below,
+      // same principle as real execution routing. Explorer, never a
+      // guess from the question's text: resolveProjectRoute's whole
+      // design is that a role is always the caller's own explicit fixed
+      // choice, never inferred per-call — ASK questions are read-only
+      // investigation, which is exactly Explorer's job.
+      const teamRoute = await this.routeProjectExecution("Explorer", projectRoot);
+      const teamModel = teamRoute.decision === "ROUTED" ? teamRoute.model
+        : teamRoute.decision === "WAIT_FOR_PROJECT_TEAM" ? teamRoute.suggestedAlternative?.model ?? null
+        : null;
+      // Only when that real assignment is one askProvider can actually
+      // call (see ASK_SUPPORTED_ADAPTERS's own doc) — a role can be
+      // validly assigned to Cursor/OpenCode Go/Zen, which ASK simply
+      // can't invoke yet, so that's a real reason to fall through below,
+      // never an error.
+      if (teamModel && ASK_SUPPORTED_ADAPTERS.has(teamModel.adapterId)) {
+        return {
+          decision: {
+            decision: "ROUTED", provider: teamModel.adapterId, model: teamModel.modelId,
+            why: `Explorer (PROJECT TEAM): ${teamRoute.why}`
+          },
+          projectRoot
+        };
+      }
+      // No active team, or Explorer's real assignment isn't ask-capable —
+      // fall back to the generic quota/capability heuristic so ASK stays
+      // useful even before a team is approved.
       const adapters = inspectAdapters({ cwd: projectRoot });
       let codexUsage = null;
       let claudeUsage = null;

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

@@ -118,9 +118,21 @@ function findAdapter(adapterId, adapters) {
   return adapters.find((adapter) => adapter.id === baseId) ?? null;
 }
 
-/** @param {object|null} usageEntry - a codex/claude usage-probe result (primary/secondary windows) */
+/**
+ * The WORST remaining headroom across both real windows (5h "primary" and
+ * weekly "secondary") — never just the primary one. A provider whose
+ * weekly quota is nearly gone must be treated that way everywhere
+ * (exclusion AND ordering) even while its 5h window still looks healthy;
+ * otherwise Kairo keeps routing to it, burning through the one budget
+ * that's actually about to run out. Mirrors the same fail-closed
+ * principle checkCandidate already applies to OpenCode Go's windows (any
+ * one window being real trouble is real trouble, full stop).
+ * @param {object|null} usageEntry - a codex/claude usage-probe result (primary/secondary windows)
+ */
 function remainingPercent(usageEntry) {
-  return usageEntry?.primary?.remainingPercent ?? null;
+  const known = [usageEntry?.primary?.remainingPercent, usageEntry?.secondary?.remainingPercent]
+    .filter((value) => typeof value === "number");
+  return known.length > 0 ? Math.min(...known) : null;
 }
 
 // Below this real remaining-quota percentage, a provider is treated as

package/src/global/intelligence/quick-ask.js

@@ -37,6 +37,32 @@ function unknown(error) {
   return { status: "error", answer: null, error: String(error) };
 }
 
+/**
+ * Resets on every real stdout/stderr chunk from the child, never an
+ * absolute deadline from process start — the same real distinction
+ * execution-adapters/opencode.js's own idle timeout draws: a real, live
+ * answer that's just taking a while (a heavier reasoning model, a cold
+ * sandbox start) must never be killed for merely being slow, only a
+ * process that's produced nothing at all for `timeoutMs` really looks
+ * hung. A single-shot ask call, so this stays local rather than reusing
+ * run-supervisor.js's own detached-run mechanism.
+ * @param {import("node:child_process").ChildProcess} child
+ * @param {number} timeoutMs
+ * @param {() => void} onIdle
+ * @returns {() => void} call to clear the timer once the call finishes
+ */
+function armIdleTimeout(child, timeoutMs, onIdle) {
+  let handle = null;
+  const reset = () => {
+    if (handle) clearTimeout(handle);
+    handle = setTimeout(onIdle, timeoutMs);
+  };
+  child.stdout?.on("data", reset);
+  child.stderr?.on("data", reset);
+  reset();
+  return () => { if (handle) clearTimeout(handle); };
+}
+
 /** @param {{question:string, model:string|null, cwd:string, spawn:Function, timeoutMs:number, env:object}} args */
 function askClaude({ question, model, cwd, spawn, timeoutMs, env }) {
   // --restricted: removes Bash/code-execution tools and WebFetch, ignores
@@ -57,11 +83,11 @@ function askClaude({ question, model, cwd, spawn, timeoutMs, env }) {
     }
     let stdout = "";
     let finished = false;
-    const timer = setTimeout(() => finish(unknown("claude -p timed out")), timeoutMs);
+    const clearIdleTimer = armIdleTimeout(child, timeoutMs, () => finish(unknown(`claude -p idle-timed out after ${timeoutMs}ms with no output`)));
     function finish(result) {
       if (finished) return;
       finished = true;
-      clearTimeout(timer);
+      clearIdleTimer();
       try { child.kill?.(); } catch { /* best effort */ }
       resolve(result);
     }
@@ -106,11 +132,11 @@ async function askCodex({ question, model, cwd, spawn, timeoutMs, env }) {
         return;
       }
       let finished = false;
-      const timer = setTimeout(() => finish(unknown("codex exec timed out")), timeoutMs);
+      const clearIdleTimer = armIdleTimeout(child, timeoutMs, () => finish(unknown(`codex exec idle-timed out after ${timeoutMs}ms with no output`)));
       function finish(result) {
         if (finished) return;
         finished = true;
-        clearTimeout(timer);
+        clearIdleTimer();
         try { child.kill?.(); } catch { /* best effort */ }
         resolve(result);
       }

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