@kal-elsam/kairo-runtime 0.16.0 → 0.18.0

package/src/global/conversation/project-router.js

@@ -0,0 +1,149 @@
+// Deterministic role -> real model resolver for Kairo's approved
+// ProjectStrategy.projectTeam. This is pure routing logic over already-
+// decided data (the human-approved team + current provider eligibility) —
+// it never spends another model call, never ranks anything itself, and
+// never reclassifies a task into a role from keywords: the caller (the
+// future Builder/Debugger/Tester orchestrator) always hands in an explicit
+// role. Execution itself — actually launching a run against the resolved
+// model, worktrees, checkpoints — is a separate, later increment; this
+// module only ever decides WHAT would run, never runs it.
+//
+// Alternative selection is DOMAIN policy, not UI policy: when a role's
+// approved assignment becomes unroutable, this module is also the one
+// place that decides what real alternative (if any) to suggest — never
+// the cockpit, the CLI, or an execution layer independently re-deriving
+// one, which would risk three different answers for the same real state.
+// The alternative itself is never invented here either — it's whichever
+// real fallback candidate buildEfficientTeam already found for this role
+// at analysis time (see project-strategy.js's projectTeam.fallback,
+// persisted, not recomputed) — this module only checks whether that
+// persisted candidate is STILL real-eligible right now.
+
+/**
+ * Whether Kairo can launch an automatic run against this real candidate
+ * right now — reads model-candidate-catalog.js's own `accessMode`
+ * ("automatic"|"manual"), the canonical source, never a hardcoded
+ * adapterId list. Cursor/OpenCode Go are "manual" today because
+ * resolveAccessMode says so, not because this module knows their names —
+ * if OpenCode Go ever gets real, proven automatic execution, that change
+ * lands once in resolveAccessMode and this router picks it up for free,
+ * with no adapter-list edit needed here.
+ */
+function isAutomatic(model) {
+  return model?.accessMode === "automatic";
+}
+
+export const PROJECT_ROUTE_DECISION = {
+  ROUTED: "ROUTED",
+  MANUAL_HANDOFF: "MANUAL_HANDOFF",
+  WAIT_FOR_PROJECT_TEAM: "WAIT_FOR_PROJECT_TEAM"
+};
+
+function assignmentRef(model, assignmentSource) {
+  if (!model) return null;
+  return { provider: model.adapterId, model, assignmentSource };
+}
+
+/** A real candidate is only ever offered as `suggestedAlternative` when it's currently automatically-executable — the same bar ROUTED itself requires. Never suggests another manual-only or currently-ineligible provider; honestly null instead. */
+function routableAlternative(model, eligibility) {
+  if (!model) return null;
+  if (!isAutomatic(model)) return null;
+  if (eligibility[model.adapterId]?.ok !== true) return null;
+  return { provider: model.adapterId, model };
+}
+
+function blocked(role, strategyFingerprint, why, { blockedAssignment = null, suggestedAlternative = null } = {}) {
+  return {
+    decision: PROJECT_ROUTE_DECISION.WAIT_FOR_PROJECT_TEAM, role, strategyFingerprint, why,
+    provider: null, model: null, assignmentSource: null,
+    blockedAssignment, suggestedAlternative
+  };
+}
+
+/**
+ * Resolves one role to the real model Kairo would delegate to right now,
+ * strictly from the approved ProjectStrategy — never the global QUALITY/
+ * EFFICIENT team, and never a fabricated fallback.
+ *
+ * Blocking rules, checked in order:
+ * 1. No strategy, or not ACTIVE (suggested/stale), or missing `projectTeam`
+ *    entirely (an old strategy built before projectTeam existed) ->
+ *    WAIT_FOR_PROJECT_TEAM, no blockedAssignment/suggestedAlternative
+ *    (there's no real known assignment to block or suggest around). No
+ *    silent migration — a pre-projectTeam strategy must be re-analyzed
+ *    and re-approved.
+ * 2. The role has no real projectTeam entry, or that entry's model is
+ *    null (no real eligible candidate was ever found for it) ->
+ *    WAIT_FOR_PROJECT_TEAM, same as above.
+ * 3. The assigned model's own real `accessMode` isn't "automatic" (Cursor/
+ *    OpenCode Go today, per resolveAccessMode — see isAutomatic) ->
+ *    MANUAL_HANDOFF, still naming the real model/provider so the caller
+ *    can show a concrete handoff ("Continue in Cursor with <model>"),
+ *    never a bare "not supported".
+ * 4. The assigned provider isn't currently eligible (quota/availability
+ *    changed since the strategy was approved) -> WAIT_FOR_PROJECT_TEAM,
+ *    with `blockedAssignment` naming the real unavailable model/reason and
+ *    `suggestedAlternative` set to the strategy's own PERSISTED fallback
+ *    for this role (see project-strategy.js) when that fallback is
+ *    itself currently real-eligible and automatically executable —
+ *    otherwise honestly null. Never a silent automatic substitution: the
+ *    caller must still explicitly confirm before anything runs on the
+ *    suggested alternative.
+ * 5. Otherwise -> ROUTED, with the real provider/model/assignmentSource
+ *    this role delegates to.
+ * @param {object} args
+ * @param {string} args.role - given explicitly by the caller, never
+ *   inferred from task text.
+ * @param {object|null} args.strategy - the persisted ProjectStrategy, or
+ *   null when none exists yet.
+ * @param {Record<string, {ok: boolean, reason?: string}>} [args.eligibility] -
+ *   CURRENT provider eligibility — may have changed since the strategy was
+ *   built/approved.
+ * @returns {{decision: "ROUTED"|"MANUAL_HANDOFF"|"WAIT_FOR_PROJECT_TEAM", role: string, provider: string|null, model: object|null, assignmentSource: string|null, strategyFingerprint: string|null, blockedAssignment: {provider: string, model: object, assignmentSource: string}|null, suggestedAlternative: {provider: string, model: object}|null, why: string}}
+ */
+export function resolveProjectRoute({ role, strategy, eligibility = {} }) {
+  const strategyFingerprint = strategy?.profileFingerprint ?? null;
+
+  if (!strategy) {
+    return blocked(role, strategyFingerprint, "No project strategy exists yet — run /project to analyze and approve one.");
+  }
+  if (strategy.status !== "active") {
+    return blocked(role, strategyFingerprint, `Project strategy is ${strategy.status?.toUpperCase() ?? "UNKNOWN"}, not ACTIVE — approve it before Kairo can delegate automatically.`);
+  }
+  if (!Array.isArray(strategy.projectTeam)) {
+    return blocked(role, strategyFingerprint, "This project strategy was approved before projectTeam existed — re-analyze and approve to enable automatic delegation.");
+  }
+
+  const entry = strategy.projectTeam.find((e) => e.role === role);
+  if (!entry || !entry.model) {
+    return blocked(role, strategyFingerprint, `No real eligible model was assigned to ${role} in this project's team.`);
+  }
+
+  const { model, assignmentSource, fallback = null } = entry;
+
+  if (!isAutomatic(model)) {
+    return {
+      decision: PROJECT_ROUTE_DECISION.MANUAL_HANDOFF, role, provider: model.adapterId, model, assignmentSource, strategyFingerprint,
+      blockedAssignment: null, suggestedAlternative: null,
+      why: `${model.adapterId} isn't executable by Kairo automatically — continue manually with ${model.displayName ?? model.modelId}.`
+    };
+  }
+
+  if (eligibility[model.adapterId]?.ok !== true) {
+    const reason = eligibility[model.adapterId]?.reason ?? "unknown reason";
+    const suggestedAlternative = routableAlternative(fallback, eligibility);
+    const why = suggestedAlternative
+      ? `${model.adapterId} is not currently eligible (${reason}) — no automatic substitution; confirm the suggested alternative for ${role} before proceeding.`
+      : `${model.adapterId} is not currently eligible (${reason}) — no automatic alternative is available for ${role} right now.`;
+    return blocked(role, strategyFingerprint, why, {
+      blockedAssignment: assignmentRef(model, assignmentSource),
+      suggestedAlternative
+    });
+  }
+
+  return {
+    decision: PROJECT_ROUTE_DECISION.ROUTED, role, provider: model.adapterId, model, assignmentSource, strategyFingerprint,
+    blockedAssignment: null, suggestedAlternative: null,
+    why: `${role} delegates to ${model.displayName ?? model.modelId} per the approved project team.`
+  };
+}

package/src/global/conversation/project-strategy-store.js

@@ -0,0 +1,64 @@
+// Persists ProjectStrategy — the approved (or suggested) real per-project
+// role assignment — under the same global `~/.harness/sessions/<projectKey>/`
+// tree session-store.js and transcript-store.js already use, but as its
+// own separate file (project-strategy.json): a strategy's lifecycle
+// (suggested -> approved -> stale) is independent of both the WorkMode and
+// the chat transcript, and none of the three should need to read the
+// others just to change.
+
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { projectKeyForPath } from "../next/project-key.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+
+export const PROJECT_STRATEGY_SCHEMA = "kairo.project-strategy/v1";
+export const PROJECT_STRATEGY_STATUSES = ["suggested", "active", "stale"];
+
+function strategyPath(homeDir, projectRoot) {
+  const { sessionsDir } = harnessHomePaths(homeDir);
+  return join(sessionsDir, projectKeyForPath(projectRoot), "project-strategy.json");
+}
+
+/**
+ * Reads the persisted ProjectStrategy for a project. Returns `null` on a
+ * missing or malformed file — unlike session-store's readSession, there is
+ * no safe default strategy to fall back to (a project genuinely has NOT
+ * been analyzed yet until one is computed), so `null` here is the honest
+ * "NOT_ANALYZED" signal the cockpit checks for.
+ * @param {string} homeDir
+ * @param {string} projectRoot
+ * @returns {Promise<object|null>}
+ */
+export async function readProjectStrategy(homeDir, projectRoot, deps = {}) {
+  const read = deps.readFile ?? readFile;
+  try {
+    const raw = await read(strategyPath(homeDir, projectRoot), "utf8");
+    const doc = JSON.parse(raw);
+    if (doc?.schema !== PROJECT_STRATEGY_SCHEMA || !PROJECT_STRATEGY_STATUSES.includes(doc.status)) return null;
+    return doc;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Persists a ProjectStrategy (create or replace — a strategy is always
+ * recomputed as a whole document, never patched field by field, so a
+ * stale nested field can never survive a refresh by accident).
+ * @param {string} homeDir
+ * @param {string} projectRoot
+ * @param {object} strategy - a ProjectStrategy document (see project-strategy.js)
+ */
+export async function writeProjectStrategy(homeDir, projectRoot, strategy, deps = {}) {
+  if (!PROJECT_STRATEGY_STATUSES.includes(strategy?.status)) {
+    throw new Error(`ProjectStrategy must have a real status (one of ${PROJECT_STRATEGY_STATUSES.join(", ")}).`);
+  }
+  const mkdirImpl = deps.mkdir ?? mkdir;
+  const writeJson = deps.writeAtomicJson ?? writeAtomicJson;
+  const path = strategyPath(homeDir, projectRoot);
+  const doc = { ...strategy, schema: PROJECT_STRATEGY_SCHEMA };
+  await mkdirImpl(dirname(path), { recursive: true });
+  await writeJson(path, doc);
+  return doc;
+}