@kal-elsam/kairo-runtime 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -5,6 +5,40 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.21.0 — 2026-09-18 (Kairo Runtime)
+
+Patch-level polish. When a role resolves to a manual-only provider
+(OpenCode Go), the `planExecution` preview now carries the exact
+real task text an automatic run would use, and the cockpit pushes it
+into the transcript ready to paste into that provider's own chat —
+instead of only naming the assigned model.
+
+### Added
+
+- `buildExecutionTaskPrompt` (service.js) is the one real formula for a
+  task's launch text, shared by `executePlan` (real automatic runs)
+  and `planExecution`'s `MANUAL_HANDOFF` preview (`taskPrompt`).
+
+## 0.20.0 — 2026-09-18 (Kairo Runtime)
+
+Minor release. Promotes Cursor to a real automatic execution provider.
+
+### Changed
+
+- Cursor's accessMode flips from "manual" to "automatic"
+  (`model-candidate-catalog.js`). Its own execution adapter already
+  builds a real, auditable non-interactive launch (`cursor-agent -p
+  --output-format stream-json`) and parses its structured event stream
+  — the same shape as Codex/Claude, and an officially documented,
+  supported use of the Cursor CLI. Real task routing now judges Cursor
+  by the exact same launchable/eligibility gate as Codex/Claude, for
+  both execution and recommendations — no more special-cased
+  manual-only rejection in `execution-router.js`'s `checkCandidate`.
+- Cursor's own opaque "auto" router model still stays manual (its
+  identity is non-deterministic, unlike a named model). OpenCode Go is
+  unaffected — it remains manual for its own, real, already-confirmed
+  Go/Zen billing-attribution ambiguity.
+
 ## 0.19.0 — 2026-09-18 (Kairo Runtime)
 
 Patch-level polish on top of 0.18.0's PROJECT TEAM work: fixes the

package/package.json

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

@@ -190,6 +190,16 @@ export async function runCockpitApp({
         return runAction("Asking PROJECT TEAM who should execute this", async () => {
           const decision = await service.planExecution({ cwd, taskId, role });
           view.showExecuteConfirm(taskId, decision);
+          // MANUAL_HANDOFF: Kairo can't launch this itself, so the real
+          // task text (the exact same one an automatic run would get —
+          // see service.js's buildExecutionTaskPrompt) goes into the
+          // transcript, ready to paste into the assigned provider's own
+          // chat — never just naming the model and leaving the human to
+          // reconstruct the prompt themselves.
+          if (decision.decision === "MANUAL_HANDOFF" && decision.taskPrompt) {
+            const modelLabel = decision.modelRef?.displayName ?? decision.model ?? "the assigned model";
+            pushTranscript("kairo", `${decision.provider} · ${modelLabel} can't be launched automatically — paste this into its chat:\n\n${decision.taskPrompt}`);
+          }
         });
       },
       onExecute: (taskId, decision) => {

package/src/global/cockpit/view.js

@@ -1258,7 +1258,7 @@ export class CockpitView {
       `Claude   ${claudeText}`,
       `Go       ${goText}`,
       `Zen      ${zenText}`,
-      `Cursor   ${entry("Cursor", "MANUAL · usage unknown")}`
+      `Cursor   ${entry("Cursor", "READY · usage unknown")}`
     ];
   }
 

package/src/global/conversation/service.js

@@ -367,6 +367,24 @@ export function createConversationService(deps = {}) {
 
   async function root(cwd) { return resolveRoot(cwd); }
 
+  /**
+   * The exact real task text an automatic run gets launched with (see
+   * executePlan) — the ONE real formula, never a second one invented for
+   * display purposes. Reused by toExecutionPreview so a MANUAL_HANDOFF
+   * preview can hand the human this same text, ready to paste into the
+   * manual-only provider's own chat, instead of just naming the model.
+   * @param {string} planMarkdown
+   */
+  function buildExecutionTaskPrompt(planMarkdown) {
+    return [
+      "Implement the explicitly approved architecture plan below.",
+      "Follow repository AGENTS.md and Gentle governance. Do not treat plan approval as any additional governance receipt.",
+      "Use safe, non-bypassed permissions for this session.",
+      "",
+      planMarkdown
+    ].join("\n");
+  }
+
   /**
    * Projects a real project-router decision into the public
    * ProjectExecutionPreview shape — never recalculates anything the
@@ -380,20 +398,28 @@ export function createConversationService(deps = {}) {
    * - Everything else (MANUAL_HANDOFF, or WAIT_FOR_PROJECT_TEAM with no
    *   real alternative): null — nothing to confirm into an automatic run.
    * @param {ReturnType<typeof resolveProjectRoute>} route
+   * @param {{planMarkdown: string}|null} [record] - present only from
+   *   planExecution (which already read the real plan record); used to
+   *   attach `taskPrompt` for a MANUAL_HANDOFF decision only — a ROUTED/
+   *   WAIT_FOR_PROJECT_TEAM preview never needs it, since executePlan
+   *   builds the real task text itself from the SAME buildExecutionTaskPrompt.
    */
-  function toExecutionPreview(route) {
+  function toExecutionPreview(route, record = null) {
     let confirmationTarget = null;
     if (route.decision === "ROUTED" && route.model) {
       confirmationTarget = { role: route.role, selection: "assigned", strategyFingerprint: route.strategyFingerprint, candidateKey: route.model.candidateKey ?? null };
     } else if (route.decision === "WAIT_FOR_PROJECT_TEAM" && route.suggestedAlternative?.model) {
       confirmationTarget = { role: route.role, selection: "suggested-alternative", strategyFingerprint: route.strategyFingerprint, candidateKey: route.suggestedAlternative.model.candidateKey ?? null };
     }
+    const taskPrompt = route.decision === "MANUAL_HANDOFF" && record?.planMarkdown
+      ? buildExecutionTaskPrompt(record.planMarkdown)
+      : null;
     return {
       decision: route.decision, role: route.role,
       provider: route.provider, model: route.model?.modelId ?? null, modelRef: route.model,
       assignmentSource: route.assignmentSource, strategyFingerprint: route.strategyFingerprint, why: route.why,
       blockedAssignment: route.blockedAssignment, suggestedAlternative: route.suggestedAlternative,
-      confirmationTarget
+      confirmationTarget, taskPrompt
     };
   }
 
@@ -496,8 +522,8 @@ export function createConversationService(deps = {}) {
         // scoredAllRaw directly, so an old generation Cursor still
         // re-exposes (e.g. Claude Sonnet 4) naturally stops competing
         // without buildAiTeam/buildEfficientTeam's own ranking logic
-        // needing to know why. Manual-only real candidates (Cursor,
-        // OpenCode Go) stay in it — this is "what Kairo can honestly
+        // needing to know why. Manual-only real candidates (OpenCode Go,
+        // and Cursor's own opaque "auto" router model) stay in it — this is "what Kairo can honestly
         // recommend", not "what Kairo can launch by itself".
         const scoredAll = buildRecommendationPool(scoredAllRaw, completeCandidateCatalog);
         // The Automatic Execution Pool: the real subset of scoredAll
@@ -961,7 +987,7 @@ export function createConversationService(deps = {}) {
       const record = await readPlan(projectRoot, taskId);
       if (!record) throw new Error(`Plan "${taskId}" not found.`);
       const route = await this.routeProjectExecution(role, projectRoot);
-      return { ...toExecutionPreview(route), projectRoot, taskId };
+      return { ...toExecutionPreview(route, record), projectRoot, taskId };
     },
     /**
      * @param {object} args
@@ -1010,13 +1036,7 @@ export function createConversationService(deps = {}) {
         if (!raced) throw error;
         return { ...publicPlan(record, raced), projectRoot, reused: true };
       }
-      const task = [
-        "Implement the explicitly approved architecture plan below.",
-        "Follow repository AGENTS.md and Gentle governance. Do not treat plan approval as any additional governance receipt.",
-        "Use safe, non-bypassed permissions for this session.",
-        "",
-        record.planMarkdown
-      ].join("\n");
+      const task = buildExecutionTaskPrompt(record.planMarkdown);
       try {
         const started = await launchRun({
           homeDir, runId, agentId: resolvedAgentId, task, cwd: projectRoot, model: resolvedModel,

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

@@ -156,40 +156,32 @@ export const LOW_QUOTA_WARN_PERCENT = 20;
  *   have the model via the Go subscription — without claiming Kairo can
  *   safely auto-execute through it yet (see opencode.js's checkAvailability
  *   for why: no per-event way to prove a run didn't silently bill Zen).
- *   It also lets Cursor be named as a real recommendation (e.g. Builder ->
- *   Cursor Composer 2.5) even though Kairo never auto-executes through it —
- *   the user continues that work manually inside the Cursor IDE; this is
- *   permanent for Cursor, not a temporary safety gap like opencode-go's.
- *   Real task routing (selectExecutionProvider/selectAskProvider) always
- *   uses the default `true` — it must never pick something guaranteed to
- *   fail at launch (run-manager.js's own launchable gate would reject it).
+ *   Cursor no longer needs this exemption: its own execution adapter
+ *   (execution-adapters/cursor.js) builds a real, auditable non-interactive
+ *   launch and Cursor's own docs support headless/CI use, so real task
+ *   routing now judges it exactly like Codex/Claude — same launchable gate,
+ *   no special case. Real task routing (selectExecutionProvider/
+ *   selectAskProvider) always 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, 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.
   if (adapterId === "opencode-zen") return { ok: false, reason: "OpenCode Zen is excluded from automatic routing (PAYG risk)" };
-  // Cursor is a deliberate manual-only destination for real task
-  // execution — recommendation and execution are different capabilities
-  // (see model-intelligence.js's role assignments): Kairo can genuinely
-  // recommend a real Cursor model for a role (Builder -> Cursor Composer
-  // 2.5, say), the same requireLaunchable:false exception opencode-go
-  // already gets below, but real task routing (requireLaunchable: true,
-  // the default) always refuses it — the user continues that work
-  // manually inside the Cursor IDE, never an automatic Kairo-launched run.
-  if (adapterId === "cursor" && requireLaunchable) {
-    return { ok: false, reason: "Cursor is manual-only — continue the work in the Cursor IDE, never auto-executed by Kairo" };
-  }
 
   const adapter = findAdapter(adapterId, adapters);
   if (!adapter) return { ok: false, reason: `${adapterId}: no adapter found` };
   if (!adapter.available) return { ok: false, reason: adapter.reason ?? `${adapterId}: not available` };
   // "launchable" means safe for Kairo to invoke programmatically — not the
-  // bar a manual recommendation needs. Cursor gets the same exemption
-  // opencode-go already has: real availability is enough to recommend it,
-  // even though (unlike opencode-go) it's exempt from launchable for a
-  // structurally different reason — it will NEVER be launchable, by design.
-  const launchableRequired = requireLaunchable || (adapterId !== "opencode-go" && adapterId !== "cursor");
+  // bar a manual recommendation needs. OpenCode Go alone keeps the
+  // exemption: real availability is enough to recommend it, even though
+  // Kairo can't safely auto-execute through it yet (unresolved Go/Zen
+  // billing-attribution gap — see opencode.js). Cursor no longer needs
+  // this exemption — its real launchability is judged the same way for
+  // both recommendation and execution now.
+  const launchableRequired = requireLaunchable || adapterId !== "opencode-go";
   if (launchableRequired && !adapter.launchable) return { ok: false, reason: adapter.reason ?? `${adapterId}: not launchable yet` };
 
   if (adapterId === "codex") {
@@ -209,11 +201,10 @@ export function checkCandidate(adapterId, { adapters, codexUsage, claudeUsage, o
     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.
+  // doc) — never fabricated from a guess. Applies to BOTH the
+  // recommendation path AND real task routing now that Cursor is a real
+  // automatic candidate — a human-reported "out of credits" must block
+  // an actual launch, not just a suggestion.
   if (adapterId === "cursor" && cursorManualQuota?.manualExhausted) {
     return { ok: false, reason: cursorManualQuota.reason ?? "Cursor marked out of credits (manual, via /project cursor exhausted)" };
   }

package/src/global/intelligence/model-candidate-catalog.js

@@ -39,7 +39,7 @@ import { matchArtificialAnalysisScore } from "./model-intelligence.js";
  * @property {string} modelName - human-readable clean name, with real effort/context/privacy variant tokens stripped (see stripDisplayVariant). Never invented — always derived from the provider's own real displayName.
  * @property {string} rawDisplayName - the provider's own displayName, completely unmodified — the real evidence modelName was derived from. Whatever stripDisplayVariant peeled off (effort/context/privacy tokens) to produce modelName is still visible here, never a separate field: /models --evidence's own "technical detail" is just this string.
  * @property {string} adapterId - "codex" | "claude" | "cursor" | "opencode-go".
- * @property {"automatic"|"manual"} accessMode - whether Kairo can actually launch this candidate itself right now, or whether it's a real, recommendable option the human runs manually (Cursor always; OpenCode Go until its own empirical automatic-execution proof lands — see this module's own doc).
+ * @property {"automatic"|"manual"} accessMode - whether Kairo can actually launch this candidate itself right now, or whether it's a real, recommendable option the human runs manually (Cursor's own "auto" router model always; OpenCode Go until its own empirical automatic-execution proof lands — see this module's own doc). Named Cursor models are automatic.
  * @property {"scored"|"partial"|"unscored"} evidenceStatus - "scored": AA matched this exact model AND reports at least one of intelligenceIndex/codingIndex. "partial": AA matched it but both composite indices are null (real match, thin evidence). "unscored": no confident AA match at all. Never role-specific — see this module's own doc for why.
  * @property {string|null} lineageKey - real, recognized model family/lineage (see LINEAGE_PARSERS) — null when the modelId doesn't match any recognized, conservative pattern. Never guessed.
  * @property {number|null} generation - a real, comparable version number within that lineage — null whenever lineageKey is null.
@@ -285,12 +285,22 @@ function applyLifecycle(catalog) {
 // automatic-execution proof this session's plan calls for
 // (`opencode run -m opencode-go/<model>`, verifying real provider
 // attribution and Go-only consumption) actually runs and passes — see
-// this module's own doc. Cursor is permanently "manual" by design (see
-// execution-router.js's own checkCandidate: real task execution always
-// refuses it, recommendation never does).
-const ACCESS_MODE_BY_ADAPTER = { codex: "automatic", claude: "automatic", cursor: "manual", "opencode-go": "manual" };
+// this module's own doc. Cursor is "automatic": its own execution
+// adapter (execution-adapters/cursor.js) already builds a real,
+// auditable non-interactive launch (`cursor-agent -p --output-format
+// stream-json`) and parses its structured event stream, the exact same
+// shape as Codex/Claude — Cursor's own docs explicitly support this
+// (headless/CI use is an intended, documented capability, not a hack).
+// The earlier "permanent manual" policy predated this adapter being
+// finished and had no technical or billing reason behind it (unlike
+// OpenCode Go's real, confirmed Go/Zen billing-attribution gap above).
+const ACCESS_MODE_BY_ADAPTER = { codex: "automatic", claude: "automatic", cursor: "automatic", "opencode-go": "manual" };
 
 function resolveAccessMode(adapterId, modelId) {
+  // Cursor's own "auto" router picks whichever underlying model it wants
+  // per request — an opaque, non-deterministic identity Kairo can't
+  // attribute to a real scored model, so THIS one candidate stays manual
+  // even though named Cursor models are now real automatic candidates.
   if (adapterId === "cursor" && modelId === "auto") return "manual";
   return ACCESS_MODE_BY_ADAPTER[adapterId] ?? "manual";
 }
@@ -437,8 +447,9 @@ export function buildRecommendationPool(scoredAll, completeCatalog) {
  * The Automatic Execution Pool: the subset of the Recommendation Pool
  * Kairo can actually launch itself, right now — real routing's own
  * candidate source, never QUALITY/EFFICIENT TEAM's. Requires BOTH a real
- * accessMode of "automatic" (Cursor/OpenCode Go are permanently or
- * currently manual — see ModelCandidateIdentity's own doc) AND real,
+ * accessMode of "automatic" (OpenCode Go is currently manual, and
+ * Cursor's own "auto" router model stays manual — see
+ * ModelCandidateIdentity's own doc) AND real,
  * current eligibility (adapter availability, quota, launchability — the
  * exact same `eligibility` object checkCandidate/execution-router.js
  * already compute, reused here rather than reimplemented). Never

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