@kal-elsam/kairo-runtime 0.23.2 → 0.25.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.25.0 — 2026-09-19 (Kairo Runtime)
+
+Minor release. Cursor joins ASK.
+
+### Changed
+
+- ASK can now call Cursor, via its real, documented read-only mode
+  (`cursor-agent --mode ask`, verified live) — never combined with
+  `--force`/`--yolo`. PROJECT TEAM roles assigned to Cursor (Architect/
+  Builder/Debugger in this project's own team) are now real ASK
+  candidates, not just execution candidates.
+- OpenCode (Go/Zen) stays excluded from ASK: verified its CLI has no
+  portable, flag-driven read-only mode — its permission model is
+  project/user-config-driven, so a read-only call can't be guaranteed
+  safe across different installs.
+
+## 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.

package/package.json

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

@@ -21,10 +21,15 @@ import { ROLE_CAPABILITIES } from "../intelligence/role-profiles.js";
 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
+// (intelligence/quick-ask.js), which only actually supports these
 // 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 (its real CLI has no
+// portable read-only mode — see quick-ask.js's own askProvider doc).
+export const ASK_SUPPORTED_ADAPTERS = new Set(["codex", "claude", "cursor"]);
 
 /**
  * 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/quick-ask.js

@@ -33,6 +33,22 @@ function buildCodexExecutionEnv(sourceEnv = process.env) {
   return env;
 }
 
+// Same real scrubbing principle as Codex/Claude above — CURSOR_API_KEY/
+// CURSOR_API_ENDPOINT are cursor-agent's own documented real auth env
+// vars (verified via `cursor-agent -p --help`), never a guess.
+const CURSOR_SAFE_ENV_KEYS = Object.freeze([
+  "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE",
+  "TMPDIR", "TERM", "CURSOR_API_KEY", "CURSOR_API_ENDPOINT", "HTTP_PROXY", "HTTPS_PROXY", "NO_PROXY",
+  "http_proxy", "https_proxy", "no_proxy", "NODE_EXTRA_CA_CERTS"
+]);
+function buildCursorExecutionEnv(sourceEnv = process.env) {
+  const env = Object.create(null);
+  for (const key of CURSOR_SAFE_ENV_KEYS) {
+    if (sourceEnv[key] != null && sourceEnv[key] !== "") env[key] = sourceEnv[key];
+  }
+  return env;
+}
+
 function unknown(error) {
   return { status: "error", answer: null, error: String(error) };
 }
@@ -102,6 +118,54 @@ function askClaude({ question, model, cwd, spawn, timeoutMs, env }) {
   });
 }
 
+/**
+ * cursor-agent's own real, documented read-only mode (verified via
+ * `cursor-agent -p --help`): "ask: Q&A style for explanations and
+ * questions (read-only)" — never combined with --force/--yolo, which
+ * would grant real write/shell access. A real invalid-model failure
+ * (verified live) exits non-zero with a plain-text error on stderr, no
+ * JSON at all — unlike Claude's/Codex's own failure shapes, so a failed
+ * JSON parse here reports the real stderr text, never a generic guess.
+ * @param {{question:string, model:string|null, cwd:string, spawn:Function, timeoutMs:number, env:object}} args
+ */
+function askCursor({ question, model, cwd, spawn, timeoutMs, env }) {
+  const args = ["-p", question, "--mode", "ask", "--output-format", "json"];
+  if (model) args.push("--model", model);
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn("cursor-agent", args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    } catch (error) {
+      resolve(unknown(error?.message ?? error));
+      return;
+    }
+    let stdout = "";
+    let stderr = "";
+    let finished = false;
+    const clearIdleTimer = armIdleTimeout(child, timeoutMs, () => finish(unknown(`cursor-agent idle-timed out after ${timeoutMs}ms with no output`)));
+    function finish(result) {
+      if (finished) return;
+      finished = true;
+      clearIdleTimer();
+      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) => {
+      let parsed;
+      try { parsed = JSON.parse(stdout); } catch {
+        return finish(unknown(stderr.trim() || `cursor-agent exited ${code} with no parseable output`));
+      }
+      if (parsed?.is_error === true || typeof parsed?.result !== "string") {
+        return finish(unknown(parsed?.result ?? stderr.trim() ?? "cursor-agent returned no answer"));
+      }
+      finish({ status: "answered", answer: parsed.result, error: null });
+    });
+  });
+}
+
 /** @param {{question:string, model:string|null, cwd:string, spawn:Function, timeoutMs:number, env:object}} args */
 async function askCodex({ question, model, cwd, spawn, timeoutMs, env }) {
   let outDir;
@@ -158,10 +222,15 @@ async function askCodex({ question, model, cwd, spawn, timeoutMs, env }) {
 
 /**
  * Asks the given provider a real, read-only question and returns its real
- * answer text. Supports Codex and Claude today; any other provider yields
- * an honest "unsupported" result rather than a guess.
+ * answer text. Supports Codex, Claude, and Cursor today; any other
+ * provider yields an honest "unsupported" result rather than a guess.
+ * OpenCode (Go/Zen) is deliberately excluded — its real CLI has no
+ * portable, CLI-flag-driven read-only mode (verified via `opencode run
+ * --help`: `--auto` only ever loosens permissions further, never
+ * restricts them), so a real read-only call can't be guaranteed safe
+ * across different users' local opencode.json permission configs.
  * @param {object} args
- * @param {"codex"|"claude"} args.provider
+ * @param {"codex"|"claude"|"cursor"} args.provider
  * @param {string} args.question
  * @param {string|null} [args.model]
  * @param {string} args.cwd
@@ -171,5 +240,6 @@ export async function askProvider({
 }) {
   if (provider === "claude") return askClaude({ question, model, cwd, spawn, timeoutMs, env: buildClaudeExecutionEnv(sourceEnv) });
   if (provider === "codex") return askCodex({ question, model, cwd, spawn, timeoutMs, env: buildCodexExecutionEnv(sourceEnv) });
+  if (provider === "cursor") return askCursor({ question, model, cwd, spawn, timeoutMs, env: buildCursorExecutionEnv(sourceEnv) });
   return { status: "unsupported", answer: null, error: `ASK is not supported for provider "${provider}" yet.` };
 }

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