@kal-elsam/kairo-runtime 0.14.0 → 0.16.0

package/src/global/components-resolve-cli.js

@@ -0,0 +1,246 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveHomeDir, harnessHomePaths } from "./paths.js";
+import { readGlobalState, writeGlobalState } from "./state.js";
+import { printJson } from "./json-output.js";
+import { formatCliCommand } from "./brand/cli.js";
+import {
+  assertExplicitApplyConsent,
+  promptApplyConfirmation,
+  shouldPromptApplyConfirmation
+} from "./apply-confirmation.js";
+import { ensureIntegrationProvidersRegistered } from "./integrations/index.js";
+import { requireIntegrationProvider } from "./integrations/provider-registry.js";
+import { SDD_HEALTH } from "./integrations/sdd-evidence.js";
+import {
+  adoptedHashesFromState,
+  recordSddAdoptions
+} from "./integrations/sdd-state.js";
+import { resolveCanonicalSddSkillFile } from "./integrations/sdd-destinations.js";
+import { assertComponentInstalled } from "./component-integration-cli.js";
+
+const DEFAULT_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+
+/** Minimal unified-style diff without external deps. */
+export function createUnifiedDiff(fromLabel, toLabel, fromText, toText) {
+  const fromLines = String(fromText ?? "").split("\n");
+  const toLines = String(toText ?? "").split("\n");
+  const lines = [`--- ${fromLabel}`, `+++ ${toLabel}`];
+  const max = Math.max(fromLines.length, toLines.length);
+  let identical = true;
+  for (let i = 0; i < max; i += 1) {
+    const a = fromLines[i];
+    const b = toLines[i];
+    if (a === b) {
+      if (a !== undefined) lines.push(` ${a}`);
+      continue;
+    }
+    identical = false;
+    if (a !== undefined) lines.push(`-${a}`);
+    if (b !== undefined) lines.push(`+${b}`);
+  }
+  if (identical) lines.push(" (no textual differences)");
+  return lines.join("\n");
+}
+
+async function buildSddContext(options) {
+  const homeDir = resolveHomeDir();
+  await assertComponentInstalled("sdd-core", { homeDir });
+  ensureIntegrationProvidersRegistered();
+  const provider = requireIntegrationProvider("sdd-core");
+  const state = await readGlobalState(harnessHomePaths(homeDir).statePath);
+  const trackedFiles = Object.fromEntries(
+    (state?.sdd?.files ?? []).map((file) => [file.destinationPath, file.hash])
+  );
+  return {
+    homeDir,
+    provider,
+    state,
+    packageRoot: options.packageRoot ?? DEFAULT_PACKAGE_ROOT,
+    requestedAgentIds: options.adapters ?? null,
+    detectedAgentIds: (state?.adapters ?? []).map((entry) => entry.id),
+    trackedFiles,
+    adoptedFiles: adoptedHashesFromState(state?.sdd),
+    personaAgentIds: state?.sdd?.personaAgentIds ?? []
+  };
+}
+
+/** Adopt conflict disk hashes into state — no file writes. */
+export async function runComponentsAdopt(options = {}) {
+  if (options.componentId !== "sdd-core") {
+    throw new Error(
+      `components adopt supports sdd-core only (got "${options.componentId}").`
+    );
+  }
+
+  const dryRun = Boolean(options.dryRun);
+  const yes = Boolean(options.yes);
+  const json = Boolean(options.json);
+  assertExplicitApplyConsent({
+    applying: !dryRun,
+    dryRun,
+    json,
+    yes,
+    interactive: null,
+    command: "components adopt sdd-core"
+  });
+
+  const ctx = await buildSddContext(options);
+  const verification = await ctx.provider.verify({
+    homeDir: ctx.homeDir,
+    packageRoot: ctx.packageRoot,
+    requestedAgentIds: ctx.requestedAgentIds,
+    detectedAgentIds: ctx.detectedAgentIds,
+    trackedFiles: ctx.trackedFiles,
+    adoptedFiles: ctx.adoptedFiles,
+    personaAgentIds: ctx.personaAgentIds
+  });
+
+  const conflicts = (verification.findings ?? []).filter(
+    (finding) => finding.status === SDD_HEALTH.CONFLICT && finding.diskHash
+  );
+  const adoptions = conflicts.map((finding) => ({
+    destinationPath: finding.destinationPath,
+    hash: finding.diskHash,
+    skillId: finding.skillId,
+    agentIds: finding.agentIds ?? [],
+    relativePath: finding.relativePath ?? "SKILL.md",
+    reason: "Adopted pre-existing disk bytes via components adopt."
+  }));
+
+  const result = {
+    provider: "sdd-core",
+    componentId: "sdd-core",
+    dryRun,
+    ok: true,
+    adopted: adoptions.length,
+    adoptions,
+    summary: verification.summary
+  };
+
+  if (dryRun) {
+    if (json) { printJson(result); return result; }
+    console.log(formatCliCommand("components adopt sdd-core"));
+    console.log(`Plan: adopt=${adoptions.length} conflict files (no writes).`);
+    for (const entry of adoptions) {
+      console.log(`  adopt    ${entry.skillId} → ${entry.destinationPath}`);
+    }
+    console.log("Dry-run only — no state updated.");
+    return result;
+  }
+
+  if (shouldPromptApplyConfirmation({ applying: true, dryRun, json, confirm: yes, interactive: null })) {
+    const accepted = await promptApplyConfirmation({
+      command: "components adopt sdd-core",
+      question: `Adopt ${adoptions.length} conflicting SDD skill file(s) as-is into Kairo state? [Y/n]: `
+    });
+    if (!accepted) {
+      result.cancelled = true;
+      result.ok = false;
+      if (json) printJson(result);
+      else console.log("Cancelled.");
+      return result;
+    }
+  }
+
+  if (adoptions.length) {
+    await writeGlobalState(
+      harnessHomePaths(ctx.homeDir).statePath,
+      recordSddAdoptions(ctx.state ?? {}, { adoptions })
+    );
+  }
+
+  result.applied = true;
+  if (json) { printJson(result); return result; }
+  console.log(formatCliCommand("components adopt sdd-core"));
+  console.log(`Adopted ${adoptions.length} file(s) into Kairo state (disk unchanged).`);
+  for (const entry of adoptions) {
+    console.log(`  adopted  ${entry.skillId} → ${entry.destinationPath}`);
+  }
+  return result;
+}
+
+/** Read-only unified diff of conflict/drifted findings vs canonical. */
+export async function runComponentsDiff(options = {}) {
+  if (options.componentId !== "sdd-core") {
+    throw new Error(
+      `components diff supports sdd-core only (got "${options.componentId}").`
+    );
+  }
+
+  const ctx = await buildSddContext(options);
+  const verification = await ctx.provider.verify({
+    homeDir: ctx.homeDir,
+    packageRoot: ctx.packageRoot,
+    requestedAgentIds: ctx.requestedAgentIds,
+    detectedAgentIds: ctx.detectedAgentIds,
+    trackedFiles: ctx.trackedFiles,
+    adoptedFiles: ctx.adoptedFiles,
+    personaAgentIds: ctx.personaAgentIds
+  });
+
+  const interesting = (verification.findings ?? []).filter(
+    (finding) => finding.status === SDD_HEALTH.CONFLICT || finding.status === SDD_HEALTH.DRIFTED
+  );
+
+  const diffs = [];
+  for (const finding of interesting) {
+    let canonicalText = "";
+    let diskText = "";
+    try {
+      const canonicalPath = resolveCanonicalSddSkillFile(
+        finding.skillId,
+        finding.relativePath ?? "SKILL.md",
+        ctx.packageRoot
+      );
+      canonicalText = await readFile(canonicalPath, "utf8");
+    } catch (error) {
+      canonicalText = `/* failed to read canonical: ${error.message} */\n`;
+    }
+    try {
+      diskText = await readFile(finding.destinationPath, "utf8");
+    } catch (error) {
+      diskText = `/* failed to read disk: ${error.message} */\n`;
+    }
+    diffs.push({
+      skillId: finding.skillId,
+      status: finding.status,
+      destinationPath: finding.destinationPath,
+      agentIds: finding.agentIds ?? [],
+      unified: createUnifiedDiff(
+        `canonical/${finding.skillId}/${finding.relativePath ?? "SKILL.md"}`,
+        finding.destinationPath,
+        canonicalText,
+        diskText
+      )
+    });
+  }
+
+  const result = {
+    provider: "sdd-core",
+    componentId: "sdd-core",
+    ok: true,
+    count: diffs.length,
+    diffs,
+    summary: verification.summary
+  };
+
+  if (options.json) {
+    printJson(result);
+    return result;
+  }
+
+  console.log(formatCliCommand("components diff sdd-core"));
+  console.log(`Findings: ${diffs.length} conflict/drifted file(s).`);
+  if (diffs.length === 0) {
+    console.log("No conflicting or drifted skill files.");
+    return result;
+  }
+  for (const entry of diffs) {
+    console.log("");
+    console.log(`## ${entry.status} ${entry.skillId} (${(entry.agentIds ?? []).join(",")})`);
+    console.log(entry.unified);
+  }
+  return result;
+}

package/src/global/connection-actions.js

@@ -0,0 +1,147 @@
+/**
+ * Recommended button actions per connection chip.
+ * Optional tools never block governance; Kairo does not brew-install externals.
+ */
+import { formatCliCommand } from "./brand/cli.js";
+
+function action(id, label, command, kind = "run") {
+  return { id, label, command, kind };
+}
+
+/** @returns {{ optional: boolean, actions: Array<{id,label,command,kind}> }} */
+export function actionsForConnection(connection) {
+  if (!connection || typeof connection !== "object") {
+    return { optional: true, actions: [] };
+  }
+  const id = connection.id;
+  const state = connection.state ?? "unknown";
+
+  switch (id) {
+    case "gentle":
+      return {
+        optional: true,
+        actions: state === "available"
+          ? [action("refresh", "Refresh", null, "refresh")]
+          : [
+            action("guide-gentle", "How to install", null, "guide"),
+            action("refresh", "Refresh after install", null, "refresh")
+          ]
+      };
+    case "hermes":
+      return {
+        optional: true,
+        actions: state === "available"
+          ? [action("refresh", "Refresh", null, "refresh")]
+          : state === "unavailable" || state === "error"
+            ? [
+              action("guide-hermes-api", "Enable API tip", null, "guide"),
+              action(
+                "start-hermes",
+                "Start Hermes gateway",
+                "hermes gateway run",
+                "configure"
+              ),
+              action("refresh", "Refresh", null, "refresh")
+            ]
+            : [
+              action("guide-hermes", "How to install", null, "guide"),
+              action("refresh", "Refresh after install", null, "refresh")
+            ]
+      };
+    case "engram":
+      return {
+        optional: true,
+        actions: state === "configured"
+          ? [action("refresh", "Refresh", null, "refresh")]
+          : state === "missing"
+            ? [
+              action("guide-engram", "How to install", null, "guide"),
+              action("refresh", "Refresh after install", null, "refresh")
+            ]
+            : [
+              action(
+                "configure-engram",
+                "Configure Engram",
+                formatCliCommand("components configure engram-memory --dry-run"),
+                "configure"
+              ),
+              action("refresh", "Refresh", null, "refresh")
+            ]
+      };
+    case "graphify": {
+      const wantsUpdate = state === "stale"
+        || /graphify update/i.test(connection.detail ?? "")
+        || /No graphify-out/i.test(connection.detail ?? "");
+      const wantsInstall = state === "missing"
+        || /Install graphify/i.test(connection.detail ?? "");
+      return {
+        optional: true,
+        actions: wantsInstall
+          ? [
+            action("guide-graphify", "How to install", null, "guide"),
+            action("refresh", "Refresh after install", null, "refresh")
+          ]
+          : wantsUpdate
+            ? [
+              action("update-graph", "Update graph", "graphify update .", "configure"),
+              action("refresh", "Refresh", null, "refresh")
+            ]
+            : [action("refresh", "Refresh", null, "refresh")]
+      };
+    }
+    case "agent":
+      return {
+        optional: false,
+        actions: state === "connected"
+          ? [action("refresh", "Refresh", null, "refresh")]
+          : [
+            action("connect-agent", "Connect Agent", formatCliCommand("mcp install"), "configure"),
+            action("refresh", "Refresh", null, "refresh")
+          ]
+      };
+    default:
+      return { optional: true, actions: [] };
+  }
+}
+
+export function enrichConnection(connection) {
+  const { optional, actions } = actionsForConnection(connection);
+  return {
+    ...connection,
+    optional,
+    actions
+  };
+}
+
+/** Top-level panel buttons that are not chip-specific. */
+export function buildSetupActions({ needsAttention = false, agentConnected = false } = {}) {
+  const actions = [];
+  actions.push({
+    id: "setup",
+    label: "Setup",
+    command: formatCliCommand("setup"),
+    primary: !needsAttention && !agentConnected,
+    detail: "Detect agents you use (Cursor, Codex, Claude, …) and prepare only those."
+  });
+  if (needsAttention) {
+    actions.push({
+      id: "repair",
+      label: "Repair",
+      command: formatCliCommand("sync"),
+      primary: true
+    });
+  }
+  if (!agentConnected) {
+    actions.push({
+      id: "connect-agent",
+      label: "Connect Agent",
+      command: formatCliCommand("mcp install"),
+      primary: !needsAttention
+    });
+  }
+  actions.push(
+    { id: "doctor", label: "Doctor", command: formatCliCommand("doctor"), primary: false },
+    { id: "refresh", label: "Refresh", command: null, primary: false }
+  );
+  return actions;
+}

package/src/global/connections.js

@@ -0,0 +1,269 @@
+/**
+ * Connection chips for IDE panel / CLI — companion probes + agent MCP registration.
+ * Read-only; never mutates configs.
+ */
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { resolveHomeDir } from "./paths.js";
+import { buildCompanionSnapshot } from "./observability/build-companion-snapshot.js";
+import { runPassiveObservabilitySnapshot } from "./observability/passive-snapshot-flight.js";
+import { inspectEngramIntegration } from "./integrations/engram-evidence.js";
+import { resolveGitHeadSha } from "./observability/graphify-probe.js";
+import { enrichConnection } from "./connection-actions.js";
+import { buildFleetReport } from "./observability/fleet-probe.js";
+
+export const CONNECTION_ACCESS = Object.freeze({
+  gentle: "Probe contract; export/import review bundles (import needs consent).",
+  hermes: "Read-only: sessions via loopback API. Never runs hermes doctor/status.",
+  engram: "Disk evidence + engram version; setup needs consent.",
+  graphify: "Read-only: query, path, explain on workspace graph.",
+  agent: "MCP tools for Cursor agents (status, runs, alerts, graph)."
+});
+
+export const MCP_CLIENTS = Object.freeze({
+  cursor: {
+    id: "cursor",
+    label: "Cursor",
+    configRelativePath: join(".cursor", "mcp.json")
+  }
+});
+
+function chip(id, label, state, access, detail) {
+  return enrichConnection({
+    id,
+    label,
+    state: typeof state === "string" && state ? state : "unknown",
+    access,
+    detail: typeof detail === "string" && detail ? detail : ""
+  });
+}
+
+function gentleDetail(state) {
+  switch (state) {
+    case "available":
+      return "Gentle AI is available for review-bundle export/import.";
+    case "missing":
+      return "Install gentle-ai separately, then Refresh.";
+    case "incompatible":
+      return "Gentle is present but the review contract is incompatible.";
+    case "error":
+      return "Gentle probe failed. Check PATH and try Doctor.";
+    default:
+      return `Gentle state: ${state}.`;
+  }
+}
+
+function hermesDetail(state) {
+  switch (state) {
+    case "available":
+      return "Hermes loopback API is reachable; sessions are read-only.";
+    case "missing":
+      return "Install Hermes Agent separately, then Refresh.";
+    case "auth_required":
+      return "Hermes API requires auth (KAIRO_HERMES_API_KEY).";
+    case "incompatible":
+      return "Hermes is present but the local API contract is incompatible.";
+    case "unavailable":
+    case "error":
+      return "Hermes binary found, but loopback API (http://127.0.0.1:8642) is down. Everyday chat is `hermes` (see https://hermes-ai.net/es/docs/quickstart/). For the Kairo chip: set API_SERVER_ENABLED=true in ~/.hermes/.env, run hermes gateway run, then Refresh. Optional.";
+    default:
+      return `Hermes state: ${state}.`;
+  }
+}
+
+function engramDetail(status) {
+  switch (status) {
+    case "configured":
+      return "Engram integration evidence looks configured on disk.";
+    case "available":
+      return "Engram binary found; some agents still need configure.";
+    case "unconfigured":
+      return "Engram binary found; configure via Settings or components configure.";
+    case "missing":
+      return "Engram not detected. Optional memory — governance still works.";
+    case "conflict":
+      return "Engram config conflict. Open Settings → Engram.";
+    case "restart_required":
+      return "Engram config written; restart the agent to activate MCP tools.";
+    case "unsupported":
+      return "Engram version unsupported by this Kairo contract.";
+    case "error":
+      return "Engram inspection failed.";
+    default:
+      return `Engram status: ${status}.`;
+  }
+}
+
+function graphifyDetail(state, graphStatus) {
+  if (graphStatus === "stale") {
+    return "Graph exists but may be stale vs git HEAD. Run graphify update .";
+  }
+  if (graphStatus === "missing") {
+    return "No graphify-out/graph.json. Run graphify update . in the workspace.";
+  }
+  if (state === "available" && (graphStatus === "ok" || graphStatus == null)) {
+    return "Graphify CLI available; graph ready for query/path/explain.";
+  }
+  if (state === "missing") {
+    return "Install graphify separately, then Refresh.";
+  }
+  if (state === "error" || graphStatus === "error" || graphStatus === "malformed") {
+    return "Graphify probe failed or graph is malformed.";
+  }
+  return `Graphify state: ${state}${graphStatus ? ` / ${graphStatus}` : ""}.`;
+}
+
+export function resolveMcpConfigPath(client = "cursor", { homeDir = resolveHomeDir() } = {}) {
+  const entry = MCP_CLIENTS[client] ?? MCP_CLIENTS.cursor;
+  return join(homeDir, entry.configRelativePath);
+}
+
+/** Healthy Cursor entry must include cwd: "." (legacy without cwd → Repair).
+ * Runtime workspace identity still prefers VSCODE_CWD when Cursor spawns under $HOME.
+ */
+export function isHealthyKairoMcpEntry(entry) {
+  if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+  if (entry.command !== "kairo") return false;
+  if (!Array.isArray(entry.args) || entry.args.length !== 1 || entry.args[0] !== "mcp") {
+    return false;
+  }
+  return entry.cwd === ".";
+}
+
+/**
+ * Read-only: is Kairo registered under mcpServers.kairo for the client?
+ * Entries without cwd: "." are broken (Repair), not connected.
+ */
+export async function detectAgentMcpRegistration({
+  client = "cursor",
+  homeDir = resolveHomeDir(),
+  readFileFn = readFile
+} = {}) {
+  const path = resolveMcpConfigPath(client, { homeDir });
+  try {
+    const raw = await readFileFn(path, "utf8");
+    const parsed = JSON.parse(raw);
+    const entry = parsed?.mcpServers?.kairo;
+    if (entry && typeof entry === "object") {
+      if (isHealthyKairoMcpEntry(entry)) {
+        return {
+          connected: true,
+          state: "connected",
+          path,
+          detail: `Kairo MCP registered in ${path}. Reload Cursor MCP if tools are missing.`
+        };
+      }
+      return {
+        connected: false,
+        state: "error",
+        path,
+        detail: "Kairo MCP entry is unhealthy (require command kairo, args [mcp], cwd \".\"). Re-run kairo mcp install --yes."
+      };
+    }
+    return {
+      connected: false,
+      state: "not_connected",
+      path,
+      detail: "Kairo MCP is not registered. Click Connect Agent (opens kairo mcp install)."
+    };
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return {
+        connected: false,
+        state: "not_connected",
+        path,
+        detail: "No Cursor MCP config yet. Click Connect Agent to create one."
+      };
+    }
+    return {
+      connected: false,
+      state: "error",
+      path,
+      detail: `Could not read ${path}: ${error?.message ?? error}`
+    };
+  }
+}
+
+/**
+ * Pure adapter: companion snapshot (+ optional agent registration) → connection chips.
+ */
+export function mapCompanionToConnections(companion = {}, agent = null) {
+  const gentleState = companion?.signals?.gentle?.state ?? "missing";
+  const hermesState = companion?.signals?.hermes?.activity?.state
+    ?? companion?.signals?.hermes?.state
+    ?? "missing";
+  const engramStatus = companion?.engram?.status ?? "missing";
+  const graphifyState = companion?.signals?.graphify?.state ?? "missing";
+  const graphStatus = companion?.signals?.graphify?.graphStatus ?? null;
+
+  const connections = [
+    chip("gentle", "Gentle", gentleState, CONNECTION_ACCESS.gentle, gentleDetail(gentleState)),
+    chip("hermes", "Hermes", hermesState, CONNECTION_ACCESS.hermes, hermesDetail(hermesState)),
+    chip("engram", "Engram", engramStatus, CONNECTION_ACCESS.engram, engramDetail(engramStatus)),
+    chip(
+      "graphify",
+      "Graphify",
+      graphStatus === "stale" ? "stale" : graphifyState,
+      CONNECTION_ACCESS.graphify,
+      graphifyDetail(graphifyState, graphStatus)
+    )
+  ];
+
+  if (agent) {
+    connections.push(chip(
+      "agent",
+      "Agent",
+      agent.state ?? (agent.connected ? "connected" : "not_connected"),
+      CONNECTION_ACCESS.agent,
+      agent.detail ?? ""
+    ));
+  }
+
+  return connections;
+}
+
+export async function buildConnectionsReport({
+  homeDir = resolveHomeDir(),
+  workspaceRoot = process.cwd(),
+  client = "cursor",
+  packageRoot = null,
+  packageName = null,
+  cliVersion = null,
+  buildCompanion = buildCompanionSnapshot,
+  buildObservability = (ctx) => runPassiveObservabilitySnapshot(ctx),
+  inspectEngram = inspectEngramIntegration,
+  detectAgent = detectAgentMcpRegistration,
+  resolveHead = resolveGitHeadSha,
+  buildFleet = buildFleetReport
+} = {}) {
+  const cwd = workspaceRoot ?? process.cwd();
+  const headSha = typeof resolveHead === "function" ? resolveHead(cwd) : null;
+  const companion = await buildCompanion({
+    inspectEngram: (ctx) => inspectEngram({ homeDir, ...(ctx ?? {}) }),
+    buildObservability,
+    observabilityContext: {
+      cwd,
+      homeDir,
+      workspaceRoot: cwd,
+      headSha,
+      packageRoot,
+      packageName,
+      cliVersion
+    }
+  });
+  const agent = await detectAgent({ client, homeDir });
+  const connections = mapCompanionToConnections(companion, agent);
+  const fleet = typeof buildFleet === "function"
+    ? await buildFleet({ homeDir })
+    : { ok: true, fleets: [] };
+  return {
+    ok: companion?.ok !== false,
+    generatedAt: companion?.generatedAt ?? new Date().toISOString(),
+    client,
+    connections,
+    fleets: fleet?.fleets ?? [],
+    activity: fleet?.activity ?? null,
+    fleetNote: fleet?.note ?? "Declared config topology — not live token usage.",
+    orchestratorAuthority: fleet?.orchestratorAuthority ?? null
+  };
+}