@kal-elsam/kairo-runtime 0.14.0 → 0.16.0

package/src/global/control-plane/attention.js

@@ -0,0 +1,141 @@
+/**
+ * Attention items and ≤2 primary actions. Gentle commands stay verbatim.
+ */
+import {
+  GENTLE_DOCTOR_COMMAND,
+  GENTLE_INSTALL_HINT,
+  GENTLE_UPGRADE_LABEL,
+  NO_ACTIVE_WORKFLOW,
+  PROVIDER,
+  WORKFLOW_KIND
+} from "./constants.js";
+
+function gentlePrimary(workflow) {
+  const provider = workflow?.provider;
+  if (provider === PROVIDER.UPGRADE_REQUIRED) {
+    return {
+      item: {
+        id: "upgrade-gentle",
+        severity: "warning",
+        message: "Gentle contract is outdated. Upgrade Gentle — do not approximate workflow."
+      },
+      action: {
+        id: "upgrade-gentle",
+        label: GENTLE_UPGRADE_LABEL,
+        command: GENTLE_DOCTOR_COMMAND
+      }
+    };
+  }
+  if (provider === PROVIDER.UNAVAILABLE) {
+    return {
+      item: {
+        id: "install-gentle",
+        severity: "warning",
+        message: GENTLE_INSTALL_HINT
+      },
+      action: {
+        id: "install-gentle",
+        label: "Install Gentle",
+        command: null
+      }
+    };
+  }
+  if (provider === PROVIDER.INCOMPATIBLE) {
+    return {
+      item: {
+        id: "gentle-incompatible",
+        severity: "error",
+        message: "Gentle response is incompatible. Fail closed."
+      },
+      action: null
+    };
+  }
+  const command = workflow?.nextTransition?.execute?.command;
+  if (provider === PROVIDER.CONNECTED && typeof command === "string" && command) {
+    const operation = workflow.nextTransition.execute.operation;
+    return {
+      item: null,
+      action: {
+        id: "gentle-next",
+        label: typeof operation === "string" && operation ? operation : "Continue Gentle",
+        command
+      }
+    };
+  }
+  return { item: null, action: null };
+}
+
+export function buildAttention({ work, workflow, team, connections }) {
+  const items = [];
+  const primaryActions = [];
+  const secondaryActions = [
+    { id: "setup", label: "Setup", command: "kairo setup --dry-run" },
+    { id: "models", label: "Models", command: "kairo fleet models" },
+    { id: "catalog", label: "Catalog", command: "kairo fleet" },
+    { id: "doctor", label: "Doctor", command: "kairo doctor" }
+  ];
+
+  const gentle = gentlePrimary(workflow);
+  if (gentle.item) items.push(gentle.item);
+  if (gentle.action) primaryActions.push(gentle.action);
+
+  if (work?.integration?.showRepair === true) {
+    items.push({
+      id: "repair-integration",
+      severity: "error",
+      message: work.integration.detail ?? "MCP integration needs repair."
+    });
+    if (primaryActions.length < 2) {
+      primaryActions.push({
+        id: "repair",
+        label: "Repair",
+        command: "kairo mcp install --yes"
+      });
+    }
+  }
+
+  if (work?.integration?.state === "missing" && primaryActions.length < 2) {
+    items.push({
+      id: "connect-mcp",
+      severity: "warning",
+      message: "Kairo MCP is not registered."
+    });
+    primaryActions.push({
+      id: "connect",
+      label: "Connect Agent",
+      command: "kairo mcp install --yes"
+    });
+  }
+
+  for (const chip of connections ?? []) {
+    if (chip?.state === "error" || chip?.state === "conflict") {
+      items.push({
+        id: `conn-${chip.id}`,
+        severity: "warning",
+        message: `${chip.label ?? chip.id}: ${chip.detail ?? chip.state}`
+      });
+    }
+  }
+
+  if (!team?.platforms?.length) {
+    items.push({
+      id: "no-platforms",
+      severity: "info",
+      message: "No platforms detected in declared fleet topology."
+    });
+  }
+
+  if (workflow?.kind === WORKFLOW_KIND.NONE && !workflow?.active) {
+    items.push({
+      id: "no-workflow",
+      severity: "info",
+      message: NO_ACTIVE_WORKFLOW
+    });
+  }
+
+  return {
+    items,
+    primaryActions: primaryActions.slice(0, 2),
+    secondaryActions
+  };
+}

package/src/global/control-plane/build-report.js

@@ -0,0 +1,146 @@
+/**
+ * Build kairo.control-plane/v1 from next + connections/fleet + Gentle adapters.
+ */
+import { buildNextReport } from "../next/next-report.js";
+import { buildConnectionsReport } from "../connections.js";
+import { resolveHomeDir } from "../paths.js";
+import {
+  CONTROL_PLANE_SCHEMA,
+  NO_ACTIVE_WORKFLOW,
+  WORKFLOW_KIND
+} from "./constants.js";
+import { buildAttention } from "./attention.js";
+import { loadGentleWorkflow } from "./gentle-adapters.js";
+import { normalizeTeam } from "./team.js";
+
+function sectionOk() {
+  return { ok: true, error: null };
+}
+
+function sectionErr(error) {
+  return { ok: false, error: String(error ?? "section_failed") };
+}
+
+export async function buildControlPlaneReport({
+  homeDir = resolveHomeDir(),
+  cwd = process.cwd(),
+  client = "cursor",
+  provider = "cursor",
+  packageRoot = null,
+  packageName = null,
+  cliVersion = null,
+  buildNext = buildNextReport,
+  buildConnections = buildConnectionsReport,
+  loadWorkflow = loadGentleWorkflow
+} = {}) {
+  const diagnostics = [];
+  const sections = {
+    work: sectionOk(),
+    workflow: sectionOk(),
+    team: sectionOk(),
+    attention: sectionOk()
+  };
+
+  let work;
+  try {
+    work = await buildNext({ homeDir, cwd, provider, client });
+  } catch (error) {
+    work = {
+      schema: "kairo.next/v1",
+      ok: false,
+      goal: null,
+      progress: [],
+      now: null,
+      blockers: [],
+      next: null,
+      conversationId: null,
+      updatedAt: null,
+      integration: {
+        state: "broken",
+        provider,
+        client,
+        mcpConnected: false,
+        enrolled: false,
+        showRepair: true,
+        detail: error instanceof Error ? error.message : String(error)
+      },
+      diagnostics: ["work_build_failed"]
+    };
+    sections.work = sectionErr("work_build_failed");
+    diagnostics.push("work_build_failed");
+  }
+
+  let connectionsReport;
+  try {
+    connectionsReport = await buildConnections({
+      homeDir,
+      workspaceRoot: cwd,
+      client,
+      packageRoot,
+      packageName,
+      cliVersion
+    });
+  } catch (error) {
+    connectionsReport = {
+      ok: false,
+      connections: [],
+      fleets: [],
+      activity: null,
+      fleetNote: null,
+      orchestratorAuthority: null
+    };
+    sections.team = sectionErr("team_build_failed");
+    diagnostics.push("team_build_failed");
+  }
+
+  const team = normalizeTeam(connectionsReport);
+  if (sections.team.ok && team.platforms.length === 0 && connectionsReport?.ok === false) {
+    sections.team = sectionErr(connectionsReport.error ?? "team_empty");
+  }
+
+  const gentle = await loadWorkflow({ cwd });
+  let workflow = gentle.workflow;
+  if (workflow && gentle.provider && workflow.provider == null) {
+    workflow = { ...workflow, provider: gentle.provider };
+  }
+  if (!gentle.ok) {
+    sections.workflow = sectionErr(gentle.error ?? "gentle_unavailable");
+    diagnostics.push(gentle.error ?? "gentle_unavailable");
+    if (!workflow?.active && !workflow?.review) {
+      workflow = {
+        kind: WORKFLOW_KIND.NONE,
+        active: false,
+        label: NO_ACTIVE_WORKFLOW,
+        phase: null,
+        nextTransition: null,
+        changeName: null,
+        review: null,
+        provider: gentle.provider ?? workflow?.provider ?? null
+      };
+    }
+  }
+
+  const attention = buildAttention({
+    work,
+    workflow,
+    team,
+    connections: team.connections
+  });
+
+  const ok = sections.work.ok || sections.team.ok;
+
+  return {
+    schema: CONTROL_PLANE_SCHEMA,
+    ok,
+    generatedAt: new Date().toISOString(),
+    client,
+    work,
+    workflow,
+    team,
+    attention,
+    sections,
+    diagnostics
+  };
+}
+
+export { normalizeTeam };

package/src/global/control-plane/cli.js

@@ -0,0 +1,36 @@
+import { resolveHomeDir } from "../paths.js";
+import { printJson } from "../json-output.js";
+import { commandHeader } from "../brand/index.js";
+import { buildControlPlaneReport } from "./build-report.js";
+
+export async function runControlPlaneCli(options = {}) {
+  const report = await buildControlPlaneReport({
+    homeDir: options.homeDir ?? resolveHomeDir(),
+    cwd: options.cwd ?? process.cwd(),
+    client: options.mcpClient ?? options.client ?? "cursor",
+    provider: options.provider ?? "cursor",
+    packageRoot: options.packageRoot ?? null,
+    packageName: options.packageName ?? null,
+    cliVersion: options.cliVersion ?? null
+  });
+
+  if (options.json) {
+    printJson(report);
+    return report;
+  }
+
+  console.log(commandHeader("Control plane"));
+  console.log(`Work · ${report.work?.integration?.state ?? "—"}`);
+  console.log(`Workflow · ${report.workflow?.label ?? "—"}`);
+  const platforms = report.team?.platforms ?? [];
+  console.log(`Team · ${platforms.length} platform(s)`);
+  for (const p of platforms) {
+    console.log(`  ${p.platform} · ${p.honesty} · agents=${p.agents?.length ?? 0}`);
+  }
+  const primary = report.attention?.primaryActions ?? [];
+  if (primary.length) {
+    console.log("Primary");
+    for (const action of primary) console.log(`- ${action.label}`);
+  }
+  return report;
+}

package/src/global/control-plane/constants.js

@@ -0,0 +1,38 @@
+/**
+ * kairo.control-plane/v1 — atomic panel report (work + workflow + team + attention).
+ */
+export const CONTROL_PLANE_SCHEMA = "kairo.control-plane/v1";
+
+export const WORKFLOW_KIND = Object.freeze({
+  SDD: "sdd",
+  REVIEW: "review",
+  DIRECT: "direct",
+  DELEGATED: "delegated",
+  NONE: "none"
+});
+
+export const HONESTY = Object.freeze({
+  LIVE: "live",
+  DECLARED: "declared",
+  OPAQUE: "opaque"
+});
+
+export const NO_ACTIVE_WORKFLOW = "No active workflow";
+
+/** Control-plane Gentle provider — distinct from observability probe states. */
+export const PROVIDER = Object.freeze({
+  CONNECTED: "connected",
+  UPGRADE_REQUIRED: "upgrade_required",
+  UNAVAILABLE: "unavailable",
+  INCOMPATIBLE: "incompatible"
+});
+
+export const PROVIDER_ERROR = Object.freeze({
+  [PROVIDER.UPGRADE_REQUIRED]: "gentle_upgrade_required",
+  [PROVIDER.UNAVAILABLE]: "gentle_unavailable",
+  [PROVIDER.INCOMPATIBLE]: "gentle_incompatible"
+});
+
+export const GENTLE_INSTALL_HINT = "Install gentle-ai separately, then Refresh.";
+export const GENTLE_UPGRADE_LABEL = "Upgrade Gentle";
+export const GENTLE_DOCTOR_COMMAND = "gentle-ai doctor";

package/src/global/control-plane/gentle-adapters.js

@@ -0,0 +1,183 @@
+/**
+ * Read-only Gentle adapters for control-plane workflow/review.
+ * Negotiate capabilities before any workflow fetch. Never invent authority.
+ */
+import { spawnSync } from "node:child_process";
+import { isAbsolute } from "node:path";
+import { probeGentle, resolveGentleBinaryPath } from "../observability/gentle-probe.js";
+import { WORKFLOW_KIND, PROVIDER } from "./constants.js";
+import {
+  emptyGentleWorkflow,
+  mapGentleProviderState,
+  providerError
+} from "./provider.js";
+import {
+  argvFromBootstrap,
+  bootstrapCommandFromProbe,
+  mapOfficialReviewStatus
+} from "./review-status.js";
+import {
+  SDD_STATUS_ARGS,
+  applySddProjection,
+  mapOfficialSddStatus
+} from "./sdd-status.js";
+
+const DEFAULT_TIMEOUT_MS = 8_000;
+
+export function parseStrictJson(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  try {
+    const parsed = JSON.parse(text.trim());
+    return parsed != null && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function extractJsonPayload(text) {
+  if (typeof text !== "string" || !text.trim()) return null;
+  const strict = parseStrictJson(text);
+  if (strict) return strict;
+  const trimmed = text.trim();
+  const fenced = trimmed.match(/```json\s*([\s\S]*?)```/i);
+  if (fenced?.[1]) {
+    try {
+      return JSON.parse(fenced[1].trim());
+    } catch {
+      return null;
+    }
+  }
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    try {
+      return JSON.parse(trimmed.slice(start, end + 1));
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function resolvedGentleBinary(probed, command) {
+  if (typeof command === "string" && isAbsolute(command)) return command;
+  const path = probed?.evidence?.find((row) => row?.kind === "binary")?.path;
+  return typeof path === "string" && isAbsolute(path) ? path : resolveGentleBinaryPath();
+}
+
+export function runGentleCommand(args, {
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  spawn = spawnSync,
+  command,
+  strict = false
+} = {}) {
+  try {
+    if (typeof command !== "string" || !isAbsolute(command)) {
+      return { ok: false, error: "gentle_incompatible", payload: null };
+    }
+    const result = spawn(command, args, {
+      cwd,
+      env,
+      encoding: "utf8",
+      timeout: timeoutMs,
+      maxBuffer: 2 * 1024 * 1024,
+      shell: false
+    });
+    if (result.error) {
+      return { ok: false, error: result.error.message || "gentle_spawn_failed", payload: null };
+    }
+    const payload = strict
+      ? parseStrictJson(result.stdout ?? "")
+      : (extractJsonPayload(result.stdout ?? "") ?? extractJsonPayload(result.stderr ?? ""));
+    if (!payload) {
+      return { ok: false, error: "gentle_parse_failed", payload: null, status: result.status };
+    }
+    if (result.status !== 0 && result.status != null) {
+      return { ok: false, error: "gentle_nonzero_status", payload, status: result.status };
+    }
+    return { ok: true, payload, status: result.status, error: null };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+      payload: null
+    };
+  }
+}
+
+function applyOfficialReview(workflow, mapped) {
+  workflow.review = mapped.review;
+  workflow.nextTransition = mapped.nextTransition;
+  if (workflow.kind === WORKFLOW_KIND.NONE && mapped.nextTransition != null) {
+    workflow.kind = WORKFLOW_KIND.REVIEW;
+    workflow.active = mapped.nextTransition?.kind === "execute" || mapped.review != null;
+    workflow.label = "Review";
+  }
+}
+
+export async function loadGentleWorkflow({
+  cwd,
+  env,
+  timeoutMs,
+  spawn,
+  command,
+  probe = probeGentle,
+  runCommand = runGentleCommand
+} = {}) {
+  const probed = await probe({ cwd, env });
+  const provider = mapGentleProviderState(probed);
+  if (provider !== PROVIDER.CONNECTED) {
+    return {
+      ok: false,
+      error: providerError(provider, probed),
+      provider,
+      workflow: emptyGentleWorkflow({ provider })
+    };
+  }
+
+  const parsed = argvFromBootstrap(bootstrapCommandFromProbe(probed), {
+    repo: cwd ?? process.cwd(),
+    binaryPath: resolvedGentleBinary(probed, command)
+  });
+  if (!parsed.ok) {
+    const incompatible = PROVIDER.INCOMPATIBLE;
+    return {
+      ok: false, error: "gentle_incompatible", provider: incompatible,
+      workflow: emptyGentleWorkflow({ provider: incompatible })
+    };
+  }
+
+  const workflow = emptyGentleWorkflow({ provider });
+  const sdd = runCommand([...SDD_STATUS_ARGS], {
+    cwd, env, timeoutMs, spawn, command: parsed.binary, strict: true
+  });
+  if (sdd.ok) {
+    const mappedSdd = mapOfficialSddStatus(sdd.payload);
+    if (mappedSdd.ok) applySddProjection(workflow, mappedSdd.projection);
+  }
+
+  const reviewRun = runCommand(parsed.argv, {
+    cwd, env, timeoutMs, spawn, command: parsed.binary, strict: true
+  });
+  if (reviewRun.ok) {
+    const mapped = mapOfficialReviewStatus(reviewRun.payload);
+    if (mapped.ok) applyOfficialReview(workflow, mapped);
+  }
+
+  if (!sdd.ok && workflow.kind === WORKFLOW_KIND.NONE && workflow.review == null) {
+    return {
+      ok: false,
+      error: sdd.error ?? "gentle_sdd_unavailable",
+      provider,
+      workflow
+    };
+  }
+  return {
+    ok: true,
+    error: sdd.ok ? null : (sdd.error ?? "gentle_sdd_unavailable"),
+    provider,
+    workflow
+  };
+}

package/src/global/control-plane/provider.js

@@ -0,0 +1,69 @@
+/**
+ * Map Gentle observability probe → control-plane provider.
+ * Version is evidence only; v1 contract is upgrade, unknown schema fails closed.
+ */
+import {
+  NO_ACTIVE_WORKFLOW,
+  PROVIDER,
+  PROVIDER_ERROR,
+  WORKFLOW_KIND
+} from "./constants.js";
+
+const LEGACY_SCHEMA = "gentle-ai.review-integration.capabilities/v1";
+const LEGACY_CONTRACT = "gentle-ai.review-integration/v1";
+
+export function emptyGentleWorkflow({ provider = null } = {}) {
+  return {
+    kind: WORKFLOW_KIND.NONE,
+    active: false,
+    label: NO_ACTIVE_WORKFLOW,
+    phase: null,
+    nextTransition: null,
+    changeName: null,
+    review: null,
+    sdd: null,
+    provider
+  };
+}
+
+export function isRecognizedLegacyContract(probe) {
+  const evidenceSchemas = (probe?.evidence ?? [])
+    .map((row) => row?.schema)
+    .filter(Boolean)
+    .join(" ");
+  const blob = `${(probe?.diagnostics ?? []).join(" ")} ${evidenceSchemas}`;
+  return blob.includes(LEGACY_SCHEMA)
+    || blob.includes(LEGACY_CONTRACT)
+    || /protocol\.major mismatch: got 1\b/.test(blob);
+}
+
+export function mapGentleProviderState(probe) {
+  if (probe == null || typeof probe !== "object" || Array.isArray(probe)) {
+    return PROVIDER.INCOMPATIBLE;
+  }
+  if (probe.state === "missing") return PROVIDER.UNAVAILABLE;
+  if (probe.state === "available" && probe.contractCompatible === true) {
+    return PROVIDER.CONNECTED;
+  }
+  if (probe.state === "error") {
+    const blob = `${probe.error ?? ""} ${(probe.diagnostics ?? []).join(" ")}`;
+    if (/parse|not an object|invalid capabilities/i.test(blob)) {
+      return PROVIDER.INCOMPATIBLE;
+    }
+    return PROVIDER.UNAVAILABLE;
+  }
+  if (probe.state === "incompatible") {
+    return isRecognizedLegacyContract(probe)
+      ? PROVIDER.UPGRADE_REQUIRED
+      : PROVIDER.INCOMPATIBLE;
+  }
+  return PROVIDER.INCOMPATIBLE;
+}
+
+export function providerError(provider, probe = null) {
+  if (provider === PROVIDER.CONNECTED) return null;
+  if (provider === PROVIDER.UNAVAILABLE && probe?.state === "error") {
+    return "gentle_capabilities_failed";
+  }
+  return PROVIDER_ERROR[provider] ?? "gentle_incompatible";
+}