@kal-elsam/kairo-runtime 0.15.0 → 0.17.0

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

@@ -0,0 +1,178 @@
+// Real, evidence-only ProjectProfile: what Kairo can actually detect about
+// THIS project (stack, commands, git recency, Graphify/CodeGraph/Engram
+// availability, docs) — never a value invented for a signal that couldn't
+// be collected. Every heavy detector here is REUSED from where it already
+// exists in this codebase (detectProject, resolveGitHeadSha, probeGraphify,
+// inspectEngramIntegration) rather than reimplemented, so this module stays
+// a thin composition layer, not a second copy of that logic.
+
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { resolve } from "node:path";
+import { detectProject } from "../../project-detection.js";
+import { resolveGitHeadSha, probeGraphify, scrubGitOverrideEnv } from "../observability/graphify-probe.js";
+import { inspectEngramIntegration } from "../integrations/engram-evidence.js";
+
+export const PROJECT_PROFILE_SCHEMA = "kairo.project-profile/v1";
+
+const SDD_DOC = "docs/ai/spec-driven-development.md";
+const TDD_DOC = "docs/ai/test-driven-development.md";
+const AGENTS_DOC = "AGENTS.md";
+
+/**
+ * Real recent-history hotspots: which files changed most often in the last
+ * 90 days, via `git log --name-only` — bounded, fail-soft (never throws;
+ * returns an empty list for a non-git or history-less project). This is
+ * the ONLY new detector this module adds rather than reusing — everything
+ * else composes an existing real function.
+ * @param {string} cwd
+ * @returns {Array<{path: string, changes: number}>}
+ */
+export function detectGitHotspots(cwd, { spawn = spawnSync, timeoutMs = 5000, env = process.env, limit = 5 } = {}) {
+  try {
+    const cleanEnv = scrubGitOverrideEnv(env);
+    const result = spawn("git", ["log", "--since=90.days", "--name-only", "--pretty=format:"], {
+      cwd, encoding: "utf8", timeout: timeoutMs, env: cleanEnv, maxBuffer: 10 * 1024 * 1024
+    });
+    if (result.status !== 0) return [];
+    const counts = new Map();
+    for (const line of String(result.stdout ?? "").split("\n")) {
+      const path = line.trim();
+      if (!path) continue;
+      counts.set(path, (counts.get(path) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, limit)
+      .map(([path, changes]) => ({ path, changes }));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Real risks Kairo can actually detect — never a guessed or generic risk.
+ * @param {object} project - detectProject() result
+ * @param {string} root
+ * @returns {Array<{kind: string, detail: string}>}
+ */
+function detectRisks(project, root) {
+  const risks = [];
+  if (project.commands.test === "Not configured") risks.push({ kind: "no-test-command", detail: "No real test script detected in package.json." });
+  if (project.commands.lint === "Not configured" && project.commands.typeCheck === "Not configured") {
+    risks.push({ kind: "no-static-checks", detail: "No real lint or typecheck script detected." });
+  }
+  if (existsSync(resolve(root, ".env"))) risks.push({ kind: "env-file-present", detail: ".env present at project root — never read into evidence without explicit consent." });
+  return risks;
+}
+
+/**
+ * Real, detected role requirements — derived strictly from what
+ * detectProject actually found (a real build/test/lint command), never
+ * from a guess about what a "typical" project needs. Explorer/Architect
+ * stay baseline (every real project needs investigation + planning);
+ * Builder/Tester/Reviewer only appear when their real command exists.
+ * @param {object} project - detectProject() result
+ * @returns {Array<{role: string, capabilities: string[], reason: string}>}
+ */
+function detectRoleRequirements(project) {
+  const requirements = [
+    { role: "Explorer", capabilities: ["reasoning", "instructionFollowing"], reason: "Baseline investigation role for every real project." },
+    { role: "Architect", capabilities: ["reasoning", "coding", "instructionFollowing"], reason: "Baseline planning role for every real project." }
+  ];
+  if (project.commands.build !== "Not configured" || project.stack !== "Unknown") {
+    requirements.push({ role: "Builder", capabilities: ["coding", "softwareExecution", "terminalExecution", "instructionFollowing"], reason: "Real stack/build command detected." });
+  }
+  if (project.commands.test !== "Not configured") {
+    requirements.push({ role: "Tester", capabilities: ["coding", "terminalExecution"], reason: `Real test command detected: ${project.commands.test}` });
+    requirements.push({ role: "Debugger", capabilities: ["reasoning", "coding", "terminalExecution", "softwareExecution"], reason: "Real test command implies real failures to debug." });
+  }
+  if (project.commands.lint !== "Not configured" || project.commands.typeCheck !== "Not configured") {
+    requirements.push({ role: "Reviewer", capabilities: ["reasoning", "coding"], reason: "Real lint/typecheck command detected." });
+  }
+  return requirements;
+}
+
+/**
+ * A real, deterministic fingerprint of the profile's own inputs (git HEAD
+ * when available, plus the real detected commands/stack) — changes exactly
+ * when the real evidence behind the profile changes, which is what
+ * ProjectStrategy's STALE detection compares against. Never a random id.
+ */
+function computeFingerprint({ headSha, project }) {
+  const basis = JSON.stringify({ headSha: headSha ?? "no-git", stack: project.stack, commands: project.commands });
+  return createHash("sha256").update(basis).digest("hex").slice(0, 16);
+}
+
+/**
+ * Composes every real detector above into one ProjectProfile — strictly
+ * read-only, no file writes, no provider calls. `confidence` reflects how
+ * much REAL evidence was actually collected, never the profile's own
+ * apparent completeness — a project with no git history and a minimal
+ * package.json genuinely IS "low" confidence, not something to round up.
+ * @param {{cwd: string}} args
+ * @param {object} [deps] - injectable for tests
+ * @returns {Promise<object>} ProjectProfile
+ */
+export async function computeProjectProfile({ cwd }, deps = {}) {
+  const detectProjectImpl = deps.detectProject ?? detectProject;
+  const resolveGitHeadShaImpl = deps.resolveGitHeadSha ?? resolveGitHeadSha;
+  const probeGraphifyImpl = deps.probeGraphify ?? probeGraphify;
+  const inspectEngramImpl = deps.inspectEngramIntegration ?? inspectEngramIntegration;
+  const detectGitHotspotsImpl = deps.detectGitHotspots ?? detectGitHotspots;
+
+  const root = resolve(cwd);
+  const project = await detectProjectImpl(root);
+  const headSha = resolveGitHeadShaImpl(root);
+  const graphify = await probeGraphifyImpl({ cwd: root, headSha });
+  const engram = inspectEngramImpl();
+  const codegraphPresent = existsSync(resolve(root, ".codegraph"));
+  const hotspots = headSha ? detectGitHotspotsImpl(root) : [];
+
+  const sdd = existsSync(resolve(root, SDD_DOC));
+  const tdd = existsSync(resolve(root, TDD_DOC));
+  const agentsDoc = existsSync(resolve(root, AGENTS_DOC));
+
+  const workflowCapabilities = [];
+  if (sdd) workflowCapabilities.push("sdd");
+  if (tdd) workflowCapabilities.push("tdd");
+
+  const evidence = [
+    { kind: "package-manifest", detail: `packageManager=${project.packageManager}` },
+    { kind: "git-head", detail: headSha ? `HEAD=${headSha.slice(0, 12)}` : "not a git repository (or HEAD unresolved)" },
+    { kind: "graphify", detail: `state=${graphify.state}` },
+    { kind: "codegraph", detail: codegraphPresent ? ".codegraph/ present" : ".codegraph/ absent" },
+    { kind: "engram", detail: `status=${engram.status}` },
+    { kind: "agents-doc", detail: agentsDoc ? "AGENTS.md present" : "AGENTS.md absent" }
+  ];
+
+  // Real, honest tiers — never rounded up because the profile LOOKS
+  // complete. High requires git history (real recency signal) AND at
+  // least one real code-intelligence integration actually available.
+  let confidence = "low";
+  const hasCodeIntelligence = graphify.state === "available" || codegraphPresent || engram.status === "configured";
+  if (headSha && project.stack !== "Unknown") {
+    confidence = hasCodeIntelligence ? "high" : "medium";
+  }
+
+  return {
+    schema: PROJECT_PROFILE_SCHEMA,
+    projectName: project.name,
+    fingerprint: computeFingerprint({ headSha, project }),
+    stack: [project.stack],
+    architecture: { pattern: project.architecturePattern },
+    quality: {
+      testCommand: project.commands.test !== "Not configured" ? project.commands.test : null,
+      lintCommand: project.commands.lint !== "Not configured" ? project.commands.lint : null,
+      typeCheckCommand: project.commands.typeCheck !== "Not configured" ? project.commands.typeCheck : null,
+      buildCommand: project.commands.build !== "Not configured" ? project.commands.build : null
+    },
+    risks: detectRisks(project, root),
+    hotspots,
+    workflowCapabilities,
+    roleRequirements: detectRoleRequirements(project),
+    evidence,
+    confidence
+  };
+}

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;
+}