@kal-elsam/kairo-runtime 0.13.1 → 0.15.0

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

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

@@ -0,0 +1,216 @@
+/**
+ * kairo.work-snapshot/v1 — semantic work state for observability.
+ * Never stores prompts, transcripts, or agent-supplied workspace identity.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, readFile, readdir } 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";
+
+export const WORK_SNAPSHOT_SCHEMA = "kairo.work-snapshot/v1";
+
+/** Known smoke/fixture conversation ids — ignored on read, never auto-deleted. */
+export const IGNORED_SMOKE_CONVERSATION_IDS = Object.freeze([
+  "echopilot-visual-smoke"
+]);
+
+const PRIVATE_KEYS = Object.freeze([
+  "prompt", "prompts", "transcript", "transcripts", "response", "messages"
+]);
+
+const TECH_LEAK_RE =
+  /\bks_[a-f0-9]{8,}\b|kairo\.(?:work|next|session)\b|call kairo_|engramRef|schema\s*[:=]/i;
+
+export function isIgnoredSmokeConversationId(id) {
+  return Boolean(id) && IGNORED_SMOKE_CONVERSATION_IDS.includes(String(id));
+}
+
+export function looksLikeTechnicalLeak(text) {
+  return TECH_LEAK_RE.test(String(text ?? ""));
+}
+
+export function assertNoWorkPrivatePayload(input) {
+  if (!input || typeof input !== "object") return;
+  for (const key of PRIVATE_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(input, key)) {
+      throw new Error(`Private field "${key}" is not allowed on work payloads.`);
+    }
+  }
+}
+
+function snapshotsDir(homeDir, projectKey) {
+  return join(harnessHomePaths(homeDir).sessionsDir, projectKey, "snapshots");
+}
+
+/** Stable file id — avoids collisions from sanitized path characters. */
+export function snapshotFileId(conversationId) {
+  return createHash("sha256").update(String(conversationId)).digest("hex").slice(0, 32);
+}
+
+function snapshotFilePath(homeDir, projectKey, conversationId) {
+  return join(snapshotsDir(homeDir, projectKey), `${snapshotFileId(conversationId)}.json`);
+}
+
+function resolveConversationId(conversationId, snapshot) {
+  const raw = conversationId ?? snapshot?.conversationId ?? null;
+  if (typeof raw !== "string" || !raw.trim()) {
+    throw new Error("conversationId is required to save a work snapshot.");
+  }
+  return raw.trim().slice(0, 160);
+}
+
+function cleanText(value, max) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (!trimmed || looksLikeTechnicalLeak(trimmed)) return null;
+  return trimmed.slice(0, max);
+}
+
+function cleanTextList(list, maxItem, maxItems) {
+  if (!Array.isArray(list)) return [];
+  return list.map((item) => cleanText(item, maxItem)).filter(Boolean).slice(0, maxItems);
+}
+
+function sanitizeDelegations(list) {
+  if (!Array.isArray(list)) return [];
+  return list
+    .map((row) => {
+      if (!row || typeof row !== "object") return null;
+      const title = cleanText(row.title ?? row.goal, 160);
+      const workId = typeof row.workId === "string" && /^kw_[a-f0-9]{32}$/i.test(row.workId)
+        ? row.workId
+        : null;
+      if (!title && !workId) return null;
+      const role = row.role === "orchestrator" || row.role === "worker" ? row.role : null;
+      const state = ["assigned", "working", "blocked", "completed", "failed"].includes(row.state)
+        ? row.state
+        : null;
+      return {
+        ...(workId ? { workId } : {}),
+        ...(title ? { title } : {}),
+        ...(role ? { role } : {}),
+        ...(state ? { state } : {})
+      };
+    })
+    .filter(Boolean)
+    .slice(0, 12);
+}
+
+export function isWorkSnapshotSchema(schema) {
+  return schema === WORK_SNAPSHOT_SCHEMA;
+}
+
+/** Build a sanitized v1 snapshot. Incomplete inputs keep nulls — never invent text. */
+export function createWorkSnapshot(input = {}) {
+  assertNoWorkPrivatePayload(input);
+  const goal = cleanText(input.goal, 160);
+  const now = cleanText(input.now, 240);
+  const next = cleanText(input.next, 240);
+  const progress = cleanTextList(input.progress, 160, 3);
+  const blockers = cleanTextList(input.blockers, 200, 12);
+  const delegations = sanitizeDelegations(input.delegations);
+  const conversationId = input.conversationId
+    ? String(input.conversationId).slice(0, 160)
+    : null;
+  const provider = input.provider ? String(input.provider).slice(0, 40) : null;
+
+  return {
+    schema: WORK_SNAPSHOT_SCHEMA,
+    goal,
+    progress,
+    now,
+    blockers,
+    next,
+    ...(delegations.length > 0 ? { delegations } : {}),
+    conversationId,
+    provider,
+    updatedAt: input.updatedAt ?? new Date().toISOString()
+  };
+}
+
+export function snapshotIsComplete(snapshot) {
+  return Boolean(
+    snapshot
+    && isWorkSnapshotSchema(snapshot.schema)
+    && snapshot.goal
+    && snapshot.now
+    && snapshot.next
+  );
+}
+
+function acceptStoredSnapshot(raw) {
+  if (!isWorkSnapshotSchema(raw?.schema)) return null;
+  if (isIgnoredSmokeConversationId(raw.conversationId)) return null;
+  return raw;
+}
+
+export async function saveWorkSnapshot(
+  homeDir,
+  projectPath,
+  conversationId,
+  snapshot,
+  deps = {}
+) {
+  const resolvedId = resolveConversationId(conversationId, snapshot);
+  const projectKey = projectKeyForPath(projectPath);
+  await mkdir(snapshotsDir(homeDir, projectKey), { recursive: true });
+  const nowIso = deps.now ? deps.now() : new Date().toISOString();
+  const payload = {
+    ...createWorkSnapshot({
+      ...snapshot,
+      conversationId: resolvedId,
+      updatedAt: nowIso
+    }),
+    projectKey,
+    updatedAt: nowIso
+  };
+  await (deps.writeAtomic ?? writeAtomicJson)(
+    snapshotFilePath(homeDir, projectKey, resolvedId),
+    payload
+  );
+  return payload;
+}
+
+export async function loadWorkSnapshot(homeDir, projectPath, conversationId) {
+  if (typeof conversationId !== "string" || !conversationId.trim()) return null;
+  const projectKey = projectKeyForPath(projectPath);
+  try {
+    const raw = JSON.parse(
+      await readFile(snapshotFilePath(homeDir, projectKey, conversationId.trim()), "utf8")
+    );
+    return acceptStoredSnapshot(raw);
+  } catch {
+    return null;
+  }
+}
+
+export async function listWorkSnapshots(homeDir, projectPath) {
+  const projectKey = projectKeyForPath(projectPath);
+  const dir = snapshotsDir(homeDir, projectKey);
+  let names = [];
+  try {
+    names = await readdir(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    if (!name.endsWith(".json")) continue;
+    try {
+      const raw = JSON.parse(await readFile(join(dir, name), "utf8"));
+      const accepted = acceptStoredSnapshot(raw);
+      if (accepted) out.push(accepted);
+    } catch {
+      // corrupt files are skipped — callers see absence, not invented content
+    }
+  }
+  return out.sort((a, b) => String(b.updatedAt).localeCompare(String(a.updatedAt)));
+}
+
+/** Most recently updated real snapshot for this workspace. */
+export async function selectLatestWorkSnapshot(homeDir, projectPath) {
+  const [latest] = await listWorkSnapshots(homeDir, projectPath);
+  return latest ?? null;
+}