@kal-elsam/kairo-runtime 0.14.0 → 0.16.0

package/src/global/mcp-install.js

@@ -0,0 +1,239 @@
+/**
+ * Register Kairo as an MCP server in a client config (Cursor v1).
+ * Consent-gated: plan by default, --yes applies. Atomic write + backup.
+ */
+import { copyFile, mkdir, readFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { writeAtomicJson } from "./runtime/write-atomic-json.js";
+import {
+  MCP_CLIENTS,
+  detectAgentMcpRegistration,
+  resolveMcpConfigPath
+} from "./connections.js";
+import { printJson } from "./json-output.js";
+import { commandHeader } from "./brand/index.js";
+import { formatCliCommand } from "./brand/cli.js";
+import {
+  buildWorkSnapshotRuleFile,
+  ensureWorkSnapshotRule,
+  resolveWorkSnapshotRulePath
+} from "./mcp/work-snapshot-rule.js";
+import { resolveHomeDir } from "./paths.js";
+
+/**
+ * Cursor MCP entry. `cwd: "."` is best-effort for clients that honor it.
+ * Cursor IDE 3.15+ may still spawn under $HOME — runtime identity then uses
+ * VSCODE_CWD / WORKSPACE_FOLDER_PATHS (see resolve-mcp-workspace.js).
+ */
+export const KAIRO_MCP_SERVER_ENTRY = Object.freeze({
+  command: "kairo",
+  args: Object.freeze(["mcp"]),
+  cwd: "."
+});
+
+export function buildKairoMcpServerEntry() {
+  return {
+    command: KAIRO_MCP_SERVER_ENTRY.command,
+    args: [...KAIRO_MCP_SERVER_ENTRY.args],
+    cwd: KAIRO_MCP_SERVER_ENTRY.cwd
+  };
+}
+
+function backupPath(configPath, stamp = Date.now()) {
+  return `${configPath}.kairo-backup.${stamp}`;
+}
+
+export function buildMcpInstallPlan({
+  client = "cursor",
+  homeDir = resolveHomeDir(),
+  existing = null,
+  alreadyConnected = false
+} = {}) {
+  const clientMeta = MCP_CLIENTS[client] ?? MCP_CLIENTS.cursor;
+  const path = resolveMcpConfigPath(client, { homeDir });
+  const entry = buildKairoMcpServerEntry();
+  const next = {
+    ...(existing && typeof existing === "object" ? existing : {}),
+    mcpServers: {
+      ...((existing && typeof existing === "object" && existing.mcpServers) || {}),
+      kairo: entry
+    }
+  };
+  return {
+    client: clientMeta.id,
+    clientLabel: clientMeta.label,
+    path,
+    alreadyConnected,
+    wouldWrite: !alreadyConnected || JSON.stringify(existing?.mcpServers?.kairo)
+      !== JSON.stringify(next.mcpServers.kairo),
+    entry: next.mcpServers.kairo,
+    next,
+    backupPath: backupPath(path),
+    rulePath: resolveWorkSnapshotRulePath(homeDir),
+    ruleBody: buildWorkSnapshotRuleFile(),
+    note: alreadyConnected
+      ? "Kairo MCP already registered; --yes rewrites the entry if it drifted."
+      : `Will add mcpServers.kairo to ${path}. Reload Cursor MCP after apply.`
+  };
+}
+
+async function readExistingConfig(path, readFileFn) {
+  try {
+    const raw = await readFileFn(path, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+/**
+ * Plan (default) or apply (--yes) Cursor MCP registration for Kairo.
+ */
+export async function runMcpInstall({
+  client = "cursor",
+  yes = false,
+  json = false,
+  homeDir = resolveHomeDir(),
+  readFileFn = readFile,
+  mkdirFn = mkdir,
+  copyFileFn = copyFile,
+  writeAtomicJsonFn = writeAtomicJson,
+  writeFileFn = null,
+  renameFn = null,
+  ensureRule = ensureWorkSnapshotRule,
+  detectAgent = detectAgentMcpRegistration,
+  now = () => Date.now()
+} = {}) {
+  if (client !== "cursor") {
+    throw new Error(
+      `Unsupported MCP client "${client}". v1 supports --client=cursor only.`
+    );
+  }
+
+  const detection = await detectAgent({ client, homeDir, readFileFn });
+  const path = detection.path ?? resolveMcpConfigPath(client, { homeDir });
+  const existing = await readExistingConfig(path, readFileFn);
+  const plan = buildMcpInstallPlan({
+    client,
+    homeDir,
+    existing,
+    alreadyConnected: detection.connected === true
+  });
+  plan.backupPath = backupPath(path, now());
+  const rulePlan = await ensureRule({
+    homeDir,
+    apply: false,
+    now,
+    readFileFn,
+    mkdirFn,
+    copyFileFn,
+    writeFileFn: writeFileFn ?? undefined,
+    renameFn: renameFn ?? undefined
+  });
+  plan.ruleWouldWrite = rulePlan.wouldWrite === true;
+  plan.rulePath = rulePlan.path;
+
+  if (!yes) {
+    const payload = {
+      ok: true,
+      applied: false,
+      plan: {
+        path: plan.path,
+        client: plan.client,
+        alreadyConnected: plan.alreadyConnected,
+        wouldWrite: plan.wouldWrite,
+        entry: plan.entry,
+        rulePath: plan.rulePath,
+        ruleWouldWrite: plan.ruleWouldWrite,
+        note: plan.note,
+        applyWith: formatCliCommand("mcp install --yes")
+      }
+    };
+    if (json) {
+      printJson(payload);
+    } else {
+      console.log(commandHeader("MCP install"));
+      console.log(`Client · ${plan.clientLabel}`);
+      console.log(`Path · ${plan.path}`);
+      console.log(`Entry · ${JSON.stringify(plan.entry)}`);
+      console.log(`Rule · ${plan.rulePath}${plan.ruleWouldWrite ? " (will write)" : " (up to date)"}`);
+      console.log(plan.note);
+      console.log(`Apply · ${formatCliCommand("mcp install --yes")}`);
+    }
+    return payload;
+  }
+
+  await mkdirFn(dirname(path), { recursive: true });
+  if (existing != null && plan.wouldWrite) {
+    await copyFileFn(path, plan.backupPath);
+  }
+  if (plan.wouldWrite) {
+    await writeAtomicJsonFn(path, plan.next);
+  }
+
+  const ruleReceipt = await ensureRule({
+    homeDir,
+    apply: true,
+    now,
+    readFileFn,
+    mkdirFn,
+    copyFileFn,
+    writeFileFn: writeFileFn ?? undefined,
+    renameFn: renameFn ?? undefined
+  });
+
+  const receipt = {
+    ok: true,
+    applied: true,
+    path,
+    backupPath: existing != null && plan.wouldWrite ? plan.backupPath : null,
+    entry: plan.entry,
+    client: plan.client,
+    rulePath: ruleReceipt.path,
+    ruleWrote: ruleReceipt.wrote === true,
+    ruleBackupPath: ruleReceipt.backupPath,
+    note: "Reload Cursor MCP (Command Palette → MCP: Restart) to load kairo_* tools."
+  };
+
+  if (json) {
+    printJson(receipt);
+  } else {
+    console.log(commandHeader("MCP install"));
+    if (plan.wouldWrite) console.log(`Wrote · ${path}`);
+    else console.log(`MCP · up to date (${path})`);
+    if (receipt.backupPath) console.log(`Backup · ${receipt.backupPath}`);
+    console.log(`Rule · ${receipt.rulePath}${receipt.ruleWrote ? " (wrote)" : " (up to date)"}`);
+    if (receipt.ruleBackupPath) console.log(`Rule backup · ${receipt.ruleBackupPath}`);
+    console.log(receipt.note);
+  }
+  return receipt;
+}
+
+export function resolveMcpServeCwd(options = {}) {
+  return options.cwdExplicit === false ? undefined : options.cwd;
+}
+
+export async function runMcpCli(options = {}) {
+  const action = options.mcpAction ?? "serve";
+  if (action === "install") {
+    return runMcpInstall({
+      client: options.mcpClient ?? "cursor",
+      yes: options.yes === true,
+      json: options.json === true,
+      homeDir: options.homeDir ?? resolveHomeDir()
+    });
+  }
+  if (action === "serve" || action == null) {
+    const { runKairoMcp } = await import("./mcp/kairo-mcp.js");
+    return runKairoMcp({
+      cwd: resolveMcpServeCwd(options),
+      packageRoot: options.packageRoot,
+      packageName: options.packageName,
+      version: options.version
+    });
+  }
+  throw new Error(
+    `Unknown mcp action "${action}". Use: ${formatCliCommand("mcp")} or ${formatCliCommand("mcp install [--yes]")}`
+  );
+}

package/src/global/next/next-cli.js

@@ -0,0 +1,35 @@
+import { resolveHomeDir } from "../paths.js";
+import { printJson } from "../json-output.js";
+import { commandHeader } from "../brand/index.js";
+import { buildNextReport } from "./next-report.js";
+
+export async function runNextCli(options = {}) {
+  const report = await buildNextReport({
+    homeDir: options.homeDir ?? resolveHomeDir(),
+    cwd: options.cwd ?? process.cwd(),
+    provider: options.provider ?? "cursor",
+    client: options.mcpClient ?? options.client ?? "cursor"
+  });
+
+  if (options.json) {
+    printJson(report);
+    return report;
+  }
+
+  console.log(commandHeader("Next"));
+  console.log(`Integration · ${report.integration.state}`);
+  if (report.goal) console.log(`Goal · ${report.goal}`);
+  if (report.now) console.log(`Now · ${report.now}`);
+  if (report.next) console.log(`Next · ${report.next}`);
+  if (report.blockers?.length) {
+    console.log("Blockers");
+    for (const item of report.blockers) console.log(`- ${item}`);
+  }
+  if (!report.goal && !report.now && !report.next) {
+    console.log("No published work snapshot for this workspace.");
+  }
+  if (report.integration.showRepair) {
+    console.log("Repair · MCP configuration looks broken. Re-run: kairo mcp install --yes");
+  }
+  return report;
+}

package/src/global/next/next-report.js

@@ -0,0 +1,145 @@
+/**
+ * kairo.next/v1 — selected work snapshot + honest integration state for the panel.
+ * Never invents Goal/Progress/Now/Blockers/Next when data is absent or corrupt.
+ */
+import { detectAgentMcpRegistration } from "../connections.js";
+import { resolveHomeDir } from "../paths.js";
+import { loadEnrollment } from "./work-enroll.js";
+import {
+  listWorkSnapshots,
+  snapshotIsComplete
+} from "./work-snapshot.js";
+
+export const NEXT_SCHEMA = "kairo.next/v1";
+
+export const INTEGRATION_STATE = Object.freeze({
+  MISSING: "missing",
+  READY: "ready",
+  ACTIVE: "active",
+  BROKEN: "broken"
+});
+
+function teamFromDelegations(delegations) {
+  if (!Array.isArray(delegations) || delegations.length === 0) return undefined;
+  const members = delegations
+    .map((row) => {
+      if (!row || typeof row !== "object") return null;
+      const title = typeof row.title === "string" ? row.title.slice(0, 160) : null;
+      const workId = typeof row.workId === "string" ? row.workId : null;
+      if (!title && !workId) return null;
+      return {
+        ...(workId ? { workId } : {}),
+        ...(title ? { title } : {}),
+        ...(row.role ? { role: row.role } : {}),
+        ...(row.state ? { state: row.state } : {})
+      };
+    })
+    .filter(Boolean);
+  return members.length > 0 ? { members } : undefined;
+}
+
+export function resolveIntegrationState({ mcp, hasUsableSnapshot }) {
+  if (mcp?.state === "error") {
+    return {
+      state: INTEGRATION_STATE.BROKEN,
+      mcpConnected: false,
+      showRepair: true,
+      detail: mcp.detail ?? "MCP configuration could not be read."
+    };
+  }
+  if (!mcp?.connected) {
+    return {
+      state: INTEGRATION_STATE.MISSING,
+      mcpConnected: false,
+      showRepair: false,
+      detail: mcp?.detail ?? "Kairo MCP is not registered."
+    };
+  }
+  if (hasUsableSnapshot) {
+    return {
+      state: INTEGRATION_STATE.ACTIVE,
+      mcpConnected: true,
+      showRepair: false,
+      detail: "MCP connected with a usable work snapshot."
+    };
+  }
+  return {
+    state: INTEGRATION_STATE.READY,
+    mcpConnected: true,
+    showRepair: false,
+    detail: "MCP connected; waiting for a published work snapshot."
+  };
+}
+
+function viewFromSnapshot(snapshot) {
+  if (!snapshot) {
+    return {
+      goal: null,
+      progress: [],
+      now: null,
+      blockers: [],
+      next: null,
+      conversationId: null,
+      updatedAt: null
+    };
+  }
+  const team = teamFromDelegations(snapshot.delegations);
+  return {
+    goal: snapshot.goal ?? null,
+    progress: Array.isArray(snapshot.progress) ? snapshot.progress : [],
+    now: snapshot.now ?? null,
+    blockers: Array.isArray(snapshot.blockers) ? snapshot.blockers : [],
+    next: snapshot.next ?? null,
+    conversationId: snapshot.conversationId ?? null,
+    updatedAt: snapshot.updatedAt ?? null,
+    ...(team ? { team } : {})
+  };
+}
+
+/**
+ * Build the next report for the runtime workspace (deps.cwd / process.cwd()).
+ */
+export async function buildNextReport({
+  homeDir = resolveHomeDir(),
+  cwd = process.cwd(),
+  provider = "cursor",
+  client = "cursor",
+  detectAgent = detectAgentMcpRegistration,
+  listSnapshots = listWorkSnapshots,
+  loadEnrollmentFn = loadEnrollment
+} = {}) {
+  const mcp = await detectAgent({ client, homeDir });
+  const listed = await listSnapshots(homeDir, cwd);
+  // Prefer newest complete snapshot — incomplete records must not hide valid work.
+  const snapshot = listed.find((row) => snapshotIsComplete(row)) ?? null;
+  const complete = snapshotIsComplete(snapshot);
+  const integrationCore = resolveIntegrationState({
+    mcp,
+    hasUsableSnapshot: complete
+  });
+  const view = viewFromSnapshot(snapshot);
+
+  let enrolled = false;
+  if (view.conversationId) {
+    const enrollment = await loadEnrollmentFn(homeDir, cwd, view.conversationId);
+    enrolled = Boolean(enrollment);
+  }
+
+  return {
+    schema: NEXT_SCHEMA,
+    ok: integrationCore.state !== INTEGRATION_STATE.BROKEN,
+    ...view,
+    integration: {
+      state: integrationCore.state,
+      provider,
+      client,
+      mcpConnected: integrationCore.mcpConnected,
+      enrolled,
+      showRepair: integrationCore.showRepair === true,
+      detail: integrationCore.detail
+    },
+    diagnostics: integrationCore.state === INTEGRATION_STATE.BROKEN
+      ? ["integration_broken"]
+      : []
+  };
+}

package/src/global/next/project-key.js

@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { resolve, sep } from "node:path";
+
+/**
+ * Canonical absolute path for workspace identity.
+ * On macOS `/tmp` → `/private/tmp`; without realpath those alias to different keys.
+ * Walks up to an existing ancestor when the leaf path does not exist yet.
+ */
+export function canonicalizeProjectPath(projectPath) {
+  const resolved = resolve(String(projectPath ?? ""));
+  try {
+    return realpathSync(resolved);
+  } catch {
+    const parts = resolved.split(sep);
+    for (let i = parts.length - 1; i > 0; i -= 1) {
+      const prefix = parts.slice(0, i).join(sep) || sep;
+      try {
+        const realPrefix = realpathSync(prefix);
+        return resolve(realPrefix, ...parts.slice(i));
+      } catch {
+        // keep walking up
+      }
+    }
+    return resolved;
+  }
+}
+
+/**
+ * Stable workspace key derived from an absolute project path.
+ * Agents must not supply this — callers compute it from runtime cwd/workspace.
+ */
+export function projectKeyForPath(projectPath) {
+  const normalized = canonicalizeProjectPath(projectPath).toLowerCase();
+  return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}

package/src/global/next/publish-work-snapshot.js

@@ -0,0 +1,116 @@
+/**
+ * Publish kairo.work-snapshot/v1 from runtime-derived workspace identity.
+ */
+import { resolveHomeDir } from "../paths.js";
+import { projectKeyForPath } from "./project-key.js";
+import { enrollConversation } from "./work-enroll.js";
+import {
+  assertNoWorkPrivatePayload,
+  createWorkSnapshot,
+  isIgnoredSmokeConversationId,
+  saveWorkSnapshot,
+  selectLatestWorkSnapshot,
+  snapshotIsComplete
+} from "./work-snapshot.js";
+
+const FORBIDDEN = Object.freeze([
+  "projectKey", "projectPath", "cwd", "homeDir", "workspaceRoot"
+]);
+
+function fail(code) {
+  return { ok: false, code, data: null, diagnostics: [code] };
+}
+
+/**
+ * Validate → enroll → atomic snapshot write.
+ * Workspace comes only from deps.cwd / process.cwd().
+ */
+export async function publishWorkSnapshot(input = {}, deps = {}) {
+  try {
+    assertNoWorkPrivatePayload(input);
+  } catch {
+    return fail("private_payload");
+  }
+  for (const key of FORBIDDEN) {
+    if (Object.prototype.hasOwnProperty.call(input, key)) {
+      return fail("forbidden_identity_fields");
+    }
+  }
+
+  const conversationId = typeof input.conversationId === "string"
+    ? input.conversationId.trim()
+    : "";
+  if (!conversationId) return fail("conversation_required");
+  if (isIgnoredSmokeConversationId(conversationId)) return fail("ignored_conversation");
+
+  const provider = typeof input.provider === "string" && input.provider.trim()
+    ? input.provider.trim().slice(0, 40)
+    : null;
+  if (!provider) return fail("provider_required");
+
+  const draft = createWorkSnapshot({
+    goal: input.goal,
+    progress: input.progress,
+    now: input.now,
+    blockers: input.blockers,
+    next: input.next,
+    delegations: input.delegations,
+    conversationId,
+    provider
+  });
+  if (!snapshotIsComplete(draft)) return fail("incomplete_snapshot");
+
+  const homeDir = deps.homeDir ?? resolveHomeDir();
+  const projectPath = deps.cwd ?? process.cwd();
+  const projectKey = projectKeyForPath(projectPath);
+  const io = { now: deps.now, writeAtomic: deps.writeAtomic };
+
+  let enrollmentResult;
+  try {
+    enrollmentResult = await (deps.enrollConversation ?? enrollConversation)(
+      homeDir, projectPath, { conversationId, provider }, io
+    );
+  } catch {
+    return fail("enroll_failed");
+  }
+
+  let saved;
+  try {
+    saved = await (deps.saveWorkSnapshot ?? saveWorkSnapshot)(
+      homeDir, projectPath, conversationId, draft, io
+    );
+  } catch {
+    return fail("snapshot_write_failed");
+  }
+
+  if (saved.projectKey !== projectKey || saved.conversationId !== conversationId) {
+    return fail("identity_mismatch");
+  }
+
+  const latest = await (deps.selectLatestWorkSnapshot ?? selectLatestWorkSnapshot)(
+    homeDir, projectPath
+  );
+
+  return {
+    ok: true,
+    code: enrollmentResult.created ? "enrolled" : "updated",
+    data: {
+      projectKey,
+      conversationId,
+      enrolled: true,
+      created: enrollmentResult.created === true,
+      snapshot: {
+        schema: saved.schema,
+        goal: saved.goal,
+        progress: saved.progress,
+        now: saved.now,
+        blockers: saved.blockers,
+        next: saved.next,
+        ...(saved.delegations ? { delegations: saved.delegations } : {}),
+        updatedAt: saved.updatedAt
+      },
+      selected: latest?.conversationId === conversationId
+    },
+    diagnostics: []
+  };
+}

package/src/global/next/work-enroll.js

@@ -0,0 +1,91 @@
+/**
+ * Idempotent conversation enrollment scoped by runtime projectKey + conversationId.
+ */
+import { mkdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+import { projectKeyForPath } from "./project-key.js";
+import { snapshotFileId } from "./work-snapshot.js";
+
+export const WORK_ENROLLMENT_SCHEMA = "kairo.work-enrollment/v1";
+
+function enrollmentPath(homeDir, projectKey, conversationId) {
+  return join(
+    harnessHomePaths(homeDir).sessionsDir,
+    projectKey,
+    "enrollments",
+    `${snapshotFileId(conversationId)}.json`
+  );
+}
+
+/** Never trusts agent-supplied projectKey — derives it from projectPath. */
+export async function enrollConversation(
+  homeDir,
+  projectPath,
+  { conversationId, provider = null } = {},
+  deps = {}
+) {
+  if (typeof conversationId !== "string" || !conversationId.trim()) {
+    throw new Error("conversationId is required to enroll.");
+  }
+  const id = conversationId.trim().slice(0, 160);
+  const projectKey = projectKeyForPath(projectPath);
+  const path = enrollmentPath(homeDir, projectKey, id);
+  await mkdir(join(path, ".."), { recursive: true });
+  const nowIso = deps.now ? deps.now() : new Date().toISOString();
+  const writeAtomic = deps.writeAtomic ?? writeAtomicJson;
+
+  let existing = null;
+  try {
+    existing = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    existing = null;
+  }
+
+  if (existing) {
+    if (
+      existing.schema !== WORK_ENROLLMENT_SCHEMA
+      || existing.projectKey !== projectKey
+      || existing.conversationId !== id
+    ) {
+      throw new Error("enrollment_identity_mismatch");
+    }
+    const refreshed = {
+      ...existing,
+      provider: provider ? String(provider).slice(0, 40) : existing.provider,
+      updatedAt: nowIso
+    };
+    await writeAtomic(path, refreshed);
+    return { created: false, enrollment: refreshed };
+  }
+
+  const enrollment = {
+    schema: WORK_ENROLLMENT_SCHEMA,
+    projectKey,
+    conversationId: id,
+    provider: provider ? String(provider).slice(0, 40) : null,
+    enrolledAt: nowIso,
+    updatedAt: nowIso
+  };
+  await writeAtomic(path, enrollment);
+  return { created: true, enrollment };
+}
+
+export async function loadEnrollment(homeDir, projectPath, conversationId) {
+  if (typeof conversationId !== "string" || !conversationId.trim()) return null;
+  const projectKey = projectKeyForPath(projectPath);
+  try {
+    const raw = JSON.parse(
+      await readFile(enrollmentPath(homeDir, projectKey, conversationId.trim()), "utf8")
+    );
+    if (
+      raw?.schema !== WORK_ENROLLMENT_SCHEMA
+      || raw.projectKey !== projectKey
+      || raw.conversationId !== conversationId.trim()
+    ) return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}