@kal-elsam/kairo-runtime 0.5.1 → 0.7.0

package/src/global/ink/cockpit-views.js

@@ -14,6 +14,7 @@ import {
 import { windowLinesForLayout } from "./cockpit-models.js";
 import { LAYOUT_MODES } from "./layout.js";
 import { formatRunsHubLines, RUNS_HUB_ITEMS } from "./cockpit-runs.js";
+import { formatReviewDetailLines, formatReviewListLines } from "./cockpit-reviews.js";
 import { formatChangesActionLines } from "./cockpit-changes.js";
 import { formatRecoveryLines } from "./cockpit-recovery.js";
 
@@ -74,6 +75,8 @@ export function renderCockpitView({
   layoutMode = LAYOUT_MODES.COMPACT,
   selectedRun,
   selectedEvents,
+  reviews = [],
+  selectedReview = null,
   changesAction = null,
   recoveryAction = null,
   colorEnabled = true
@@ -112,7 +115,7 @@ export function renderCockpitView({
         formatRunsHubLines(RUNS_HUB_ITEMS),
         listIndex,
         colorEnabled,
-        "Choose Active runs, History, or New run."
+        "Choose Active runs, History, Reviews, or New run."
       );
     case ORCHESTRATOR_VIEWS.ACTIVE_RUNS:
       return listBlock(
@@ -136,6 +139,14 @@ export function renderCockpitView({
         colorEnabled,
         "Open Runs after governance is healthy."
       );
+    case ORCHESTRATOR_VIEWS.REVIEWS:
+      return listBlock(
+        "Reviews",
+        formatReviewListLines(reviews),
+        listIndex,
+        colorEnabled,
+        "Receipts are read-only. Launch reviews via kairo review --agent codex|pi."
+      );
     case ORCHESTRATOR_VIEWS.LAUNCH:
       if (launchableAgents.length === 0) {
         return React.createElement(CockpitEmptyState, {
@@ -165,6 +176,12 @@ export function renderCockpitView({
         formatRunDetailLines(selectedRun, selectedEvents)
           .map((line) => React.createElement(Text, { key: line }, line))
       );
+    case ORCHESTRATOR_VIEWS.REVIEW_DETAIL:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Review detail"),
+        formatReviewDetailLines(selectedReview)
+          .map((line) => React.createElement(Text, { key: line }, line))
+      );
     case ORCHESTRATOR_VIEWS.DIAGNOSTICS:
       return governanceList(
         "System health",
@@ -178,7 +195,7 @@ export function renderCockpitView({
         React.createElement(Text, null, "Kairo keeps IDEs and agents aligned with project architecture and workflows."),
         React.createElement(Text, null, "Primary flow: scan → findings → preview → confirm → apply → re-scan."),
         React.createElement(Text, null, "↑↓ navigate · Enter open · Esc back/exit · R refresh/retry · ? help"),
-        React.createElement(Text, null, "Runs are secondary after setup and repairs.")
+        React.createElement(Text, null, "Runs are secondary after setup and repairs. Reviews are read-only receipts.")
       );
     default: {
       const _exhaustive = view;

package/src/global/ink/orchestrator-app.js

@@ -25,6 +25,7 @@ import {
 import { buildControlCenterModel } from "./cockpit-control-center.js";
 import { resolveEnterNavIntent } from "./cockpit-enter.js";
 import { resolveRunsHubItem, RUNS_HUB_ITEMS } from "./cockpit-runs.js";
+import { selectReviewFromList } from "./cockpit-reviews.js";
 import { resolveProjectReadiness } from "../dashboard-guidance.js";
 import { CONTROL_PLANE_HEALTH } from "../control-plane-snapshot.js";
 import { CockpitShell } from "./cockpit/primitives.js";
@@ -142,6 +143,7 @@ export function OrchestratorApp({
         return;
       }
       data.setSelectedRun(null);
+      data.setSelectedReview(null);
       data.resetLaunchWizard();
       dispatch({ type: "escape" });
       return;
@@ -158,9 +160,11 @@ export function OrchestratorApp({
         ? (data.dashboard?.activeRuns ?? []).length
         : ui.view === ORCHESTRATOR_VIEWS.RECENT_RUNS
           ? (data.dashboard?.recentRuns ?? []).length
-          : ui.view === ORCHESTRATOR_VIEWS.ACTIVITY
-            ? listRecoverySnapshots(data.snapshot).length
-            : 0;
+          : ui.view === ORCHESTRATOR_VIEWS.REVIEWS
+            ? (data.reviews ?? []).length
+            : ui.view === ORCHESTRATOR_VIEWS.ACTIVITY
+              ? listRecoverySnapshots(data.snapshot).length
+              : 0;
 
     let routed = null;
     if (key.tab) {
@@ -229,6 +233,9 @@ export function OrchestratorApp({
       if (hubItem.action === "launch") {
         data.resetLaunchWizard();
       }
+      if (hubItem.view === ORCHESTRATOR_VIEWS.REVIEWS) {
+        data.loadReviews().catch(() => {});
+      }
       dispatch({
         type: "set-view",
         view: hubItem.view,
@@ -247,6 +254,13 @@ export function OrchestratorApp({
       return;
     }
 
+    if (ui.region === COCKPIT_REGIONS.CONTENT
+      && ui.view === ORCHESTRATOR_VIEWS.REVIEWS
+      && key.return) {
+      data.openReviewDetail(selectReviewFromList(data.reviews ?? [], ui.listIndex), dispatch);
+      return;
+    }
+
     if (ui.view === ORCHESTRATOR_VIEWS.RUN_DETAIL) {
       if (inputKey.toLowerCase() === "c" && isRunCancellable(data.selectedRun)) {
         data.handleCancelRun();
@@ -304,6 +318,10 @@ export function OrchestratorApp({
     }
 
     if (inputKey.toLowerCase() === "r" && ui.view !== ORCHESTRATOR_VIEWS.LAUNCH) {
+      if (ui.view === ORCHESTRATOR_VIEWS.REVIEWS || ui.view === ORCHESTRATOR_VIEWS.REVIEW_DETAIL) {
+        data.loadReviews().catch(() => {});
+        return;
+      }
       data.reload().catch(() => {});
     }
   });
@@ -406,6 +424,8 @@ export function OrchestratorApp({
         launchableAgents: data.launchableAgents,
         selectedRun: data.selectedRun,
         selectedEvents: data.selectedEvents,
+        reviews: data.reviews,
+        selectedReview: data.selectedReview,
         changesAction: data.changesAction,
         recoveryAction: data.recoveryAction,
         controlCenter,

package/src/global/ink/orchestrator-state.js

@@ -22,6 +22,8 @@ export const ORCHESTRATOR_VIEWS = {
   ACTIVE_RUNS: "active-runs",
   RECENT_RUNS: "recent-runs",
   RUN_DETAIL: "run-detail",
+  REVIEWS: "reviews",
+  REVIEW_DETAIL: "review-detail",
   PROVIDERS: "providers",
   LAUNCH: "launch",
   DIAGNOSTICS: "diagnostics",

package/src/global/ink/use-orchestrator-data.js

@@ -33,6 +33,8 @@ import {
   listRecoverySnapshots,
   reduceRecoveryAction
 } from "./cockpit-recovery.js";
+import { listReviewReceipts } from "../runtime/review/review-receipts.js";
+import { assertReceiptSecretFree } from "../runtime/review/review-validate.js";
 
 export function useOrchestratorData({
   homeDir,
@@ -50,6 +52,8 @@ export function useOrchestratorData({
   const [snapshot, setSnapshot] = useState(null);
   const [selectedRun, setSelectedRun] = useState(null);
   const [selectedEvents, setSelectedEvents] = useState([]);
+  const [reviews, setReviews] = useState([]);
+  const [selectedReview, setSelectedReview] = useState(null);
   const [statusMessage, setStatusMessage] = useState(null);
   const [launchAgentIndex, setLaunchAgentIndex] = useState(0);
   const [launchStep, setLaunchStep] = useState(LAUNCH_WIZARD_STEPS.AGENT);
@@ -124,6 +128,27 @@ export function useOrchestratorData({
     });
   };
 
+  const loadReviews = async () => {
+    const receipts = (await listReviewReceipts({ homeDir, limit: 50 }))
+      .map((receipt) => assertReceiptSecretFree(receipt));
+    setReviews(receipts);
+    if (selectedReview) {
+      const refreshed = receipts.find((entry) => entry.reviewId === selectedReview.reviewId) ?? null;
+      setSelectedReview(refreshed);
+    }
+    return receipts;
+  };
+
+  const openReviewDetail = (receipt, dispatch) => {
+    if (!receipt) return;
+    setSelectedReview(assertReceiptSecretFree(receipt));
+    dispatch({
+      type: "set-view",
+      view: ORCHESTRATOR_VIEWS.REVIEW_DETAIL,
+      returnView: ORCHESTRATOR_VIEWS.REVIEWS
+    });
+  };
+
   const handleLaunch = async (draft, profile, dispatch) => {
     if (!draft.agentId || !draft.task.trim()) {
       setError("Agent and task are required.");
@@ -353,6 +378,9 @@ export function useOrchestratorData({
     selectedRun,
     setSelectedRun,
     selectedEvents,
+    reviews,
+    selectedReview,
+    setSelectedReview,
     statusMessage,
     launchAgentIndex,
     setLaunchAgentIndex,
@@ -369,6 +397,8 @@ export function useOrchestratorData({
     reload,
     resetLaunchWizard,
     openRunDetail,
+    loadReviews,
+    openReviewDetail,
     handleLaunch,
     handleCancelRun,
     previewChanges,

package/src/global/integrations/engram-evidence.js

@@ -3,12 +3,13 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { probeCommand } from "../cli-probe.js";
 
-export const KAIRO_ENGRAM_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude"]);
+export const KAIRO_ENGRAM_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude", "pi"]);
 export const ENGRAM_SETUP_SLUG_BY_AGENT = Object.freeze({
   cursor: "cursor",
   codex: "codex",
   opencode: "opencode",
-  claude: "claude-code"
+  claude: "claude-code",
+  pi: "pi"
 });
 export const ENGRAM_MIN_VERSION = "1.19.0";
 export const ENGRAM_MAX_MAJOR = 2;
@@ -110,7 +111,7 @@ export function inspectEngramAgentConfig(agentId, { homeDir = homedir() } = {})
   const conflicts = evidence.filter((item) => item.conflict);
   let status = ENGRAM_INTEGRATION_STATUS.UNCONFIGURED;
   if (conflicts.length > 0) status = ENGRAM_INTEGRATION_STATUS.CONFLICT;
-  else if (evidence.some((item) => item.present && item.kind === "mcp")) {
+  else if (isEngramAgentConfigured(agentId, evidence)) {
     status = ENGRAM_INTEGRATION_STATUS.CONFIGURED;
   }
   return { id: agentId, slug, status, evidence };
@@ -165,9 +166,46 @@ function collectAgentEvidence(agentId, homeDir) {
       fileEvidence(join(homeDir, ".cursor", "rules", "engram.mdc"), "protocol")
     ];
   }
+  if (agentId === "pi") {
+    return [
+      piSettingsPackagesEvidence(join(homeDir, ".pi", "agent", "settings.json")),
+      jsonKeyEvidence(join(homeDir, ".pi", "agent", "mcp.json"), ["mcpServers", "engram"], "mcp")
+    ];
+  }
   throw new Error(`Unsupported Engram agent "${agentId}".`);
 }
 
+function isEngramAgentConfigured(agentId, evidence) {
+  if (agentId === "pi") {
+    return evidence.length > 0 && evidence.every((item) => item.present && !item.conflict);
+  }
+  return evidence.some((item) => item.present && item.kind === "mcp");
+}
+
+function piSettingsPackagesEvidence(path) {
+  const required = ["npm:gentle-engram", "npm:pi-mcp-adapter"];
+  if (!existsSync(path)) {
+    return { path, kind: "settings", present: false, conflict: false, required };
+  }
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    if (data == null || typeof data !== "object" || Array.isArray(data)) {
+      return { path, kind: "settings", present: false, conflict: true, required, detail: "invalid structure" };
+    }
+    const packages = Array.isArray(data.packages) ? data.packages : null;
+    if (packages == null) {
+      return { path, kind: "settings", present: false, conflict: true, required, detail: "invalid structure" };
+    }
+    const normalized = packages.map((entry) => String(entry));
+    const present = required.every((req) =>
+      normalized.some((entry) => entry === req || entry.startsWith(`${req}@`))
+    );
+    return { path, kind: "settings", present, conflict: false, required };
+  } catch {
+    return { path, kind: "settings", present: false, conflict: true, required, detail: "unreadable json" };
+  }
+}
+
 function fileEvidence(path, kind) {
   return { path, kind, present: existsSync(path), conflict: false };
 }

package/src/global/integrations/sdd-destinations.js

@@ -12,8 +12,8 @@ export const SDD_SKILL_IDS = Object.freeze([
   "sdd-archive"
 ]);
 
-export const SDD_MANAGED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude"]);
-export const SDD_SHARED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode"]);
+export const SDD_MANAGED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "claude", "pi"]);
+export const SDD_SHARED_AGENT_IDS = Object.freeze(["cursor", "codex", "opencode", "pi"]);
 export const SDD_PERSONA_IDS = Object.freeze(["off", "teaching"]);
 
 export function resolveSddAgentSelection({

package/src/global/paths.js

@@ -18,6 +18,7 @@ export function harnessHomePaths(homeDir) {
     profilePath: join(root, "profile.json"),
     historyPath: join(root, "history.jsonl"),
     runsDir: join(root, "runs"),
+    reviewsDir: join(root, "reviews"),
     coreDir: join(root, "core"),
     backupsDir: join(root, "backups")
   };

package/src/global/registry.js

@@ -4,8 +4,9 @@ import claude from "./adapters/claude.js";
 import codex from "./adapters/codex.js";
 import cursor from "./adapters/cursor.js";
 import opencode from "./adapters/opencode.js";
+import pi from "./adapters/pi.js";
 
-const ADAPTERS = [cursor, codex, opencode, claude];
+const ADAPTERS = [cursor, codex, opencode, claude, pi];
 
 export const GLOBAL_AGENT_IDS = ADAPTERS.map((adapter) => adapter.id);
 

package/src/global/runtime/execution-adapters/codex.js

@@ -71,7 +71,8 @@ export default createExecutionAdapter({
     tokens: true,
     diff: false,
     cancel: true,
-    transcript: true
+    transcript: true,
+    reviewCompatible: true
   },
   buildLaunch: buildCodexLaunch,
   parseEventLine: parseCodexEventLine

package/src/global/runtime/execution-adapters/create-execution-adapter.js

@@ -20,6 +20,7 @@ export function createExecutionAdapter({
       diff: false,
       cancel: true,
       transcript: false,
+      reviewCompatible: false,
       ...capabilities
     },
 

package/src/global/runtime/execution-adapters/index.js

@@ -2,8 +2,9 @@ import cursor from "./cursor.js";
 import codex from "./codex.js";
 import claude from "./claude.js";
 import opencode from "./opencode.js";
+import pi from "./pi.js";
 
-const EXECUTION_ADAPTERS = [cursor, codex, claude, opencode];
+const EXECUTION_ADAPTERS = [cursor, codex, claude, opencode, pi];
 
 export const EXECUTION_ADAPTER_IDS = EXECUTION_ADAPTERS.map((adapter) => adapter.id);
 
@@ -25,6 +26,7 @@ export function inspectExecutionAdapters(context = {}) {
     label: adapter.label,
     executable: adapter.executable,
     capabilities: adapter.capabilities,
+    reviewCompatible: Boolean(adapter.capabilities?.reviewCompatible),
     ...adapter.availability(context)
   }));
 }

package/src/global/runtime/execution-adapters/pi.js

@@ -0,0 +1,184 @@
+import { createExecutionAdapter, parseNdjsonLine } from "./create-execution-adapter.js";
+import { isExecutableAvailable, probeCommand } from "../../cli-probe.js";
+
+const EXECUTABLE = "pi";
+const READ_ONLY_TOOLS = "read,grep,find,ls";
+
+const LIFECYCLE_KINDS = new Set([
+  "session",
+  "agent_start",
+  "agent_end",
+  "turn_start",
+  "message_start",
+  "message_update",
+  "compaction_start",
+  "compaction_end",
+  "auto_retry_start",
+  "auto_retry_end",
+  "queue_update",
+  "summarization_retry_scheduled",
+  "summarization_retry_attempt_start",
+  "summarization_retry_finished"
+]);
+
+export function buildPiPermissionsArgs(permissions = []) {
+  if (!Array.isArray(permissions) || permissions.length === 0) return [];
+
+  const normalized = [...new Set(permissions.map((entry) => String(entry).toLowerCase()))];
+  if (normalized.length === 1 && normalized[0] === "read-only") {
+    return ["--tools", READ_ONLY_TOOLS];
+  }
+
+  throw new Error(
+    `Pi permissions only support "read-only" in Kairo 0.6.0 (got: ${permissions.join(", ")}). `
+    + "Other aliases are rejected and are never translated to --approve."
+  );
+}
+
+export function buildPiLaunch({ task, cwd, model, permissions = [], env = process.env } = {}) {
+  const args = [
+    "--mode",
+    "json",
+    "--no-session",
+    ...buildPiPermissionsArgs(permissions)
+  ];
+
+  if (model) {
+    args.push("--model", model);
+  }
+
+  args.push(task);
+
+  return {
+    command: EXECUTABLE,
+    args,
+    cwd,
+    env
+  };
+}
+
+export function checkPiAvailability(context = {}) {
+  const env = context.env ?? process.env;
+  const probe = context.probeImpl ?? probeCommand;
+  const availableCheck = context.isAvailableImpl ?? isExecutableAvailable;
+
+  if (!availableCheck(EXECUTABLE, { env })) {
+    return {
+      available: false,
+      compatible: false,
+      launchable: false,
+      reason: 'Pi CLI "pi" is not on PATH.'
+    };
+  }
+
+  const help = probe(EXECUTABLE, ["--help"], { env, timeoutMs: 5000 });
+  const text = `${help.stdout ?? ""}\n${help.stderr ?? ""}`;
+  const hasMode = /--mode\b/.test(text);
+  const hasNoSession = /--no-session\b/.test(text);
+
+  if (!help.ok || !hasMode || !hasNoSession) {
+    return {
+      available: true,
+      compatible: false,
+      launchable: false,
+      reason: "Pi CLI is missing required --mode / --no-session flags for auditable JSON runs."
+    };
+  }
+
+  return {
+    available: true,
+    compatible: true,
+    launchable: true,
+    reason: null
+  };
+}
+
+export function parsePiEventLine(line) {
+  const parsed = parseNdjsonLine(line);
+  if (!parsed || typeof parsed !== "object") return null;
+
+  if (parsed.type === "tool_execution_start") {
+    return {
+      type: "tool_call",
+      tool_name: parsed.toolName ?? "unknown",
+      status: "started",
+      id: parsed.toolCallId ?? null
+    };
+  }
+
+  if (parsed.type === "tool_execution_end") {
+    return {
+      type: "tool_result",
+      tool_name: parsed.toolName ?? "unknown",
+      status: parsed.isError ? "error" : "completed",
+      id: parsed.toolCallId ?? null
+    };
+  }
+
+  if (parsed.type === "tool_execution_update") {
+    return null;
+  }
+
+  if (parsed.type === "message_end") {
+    if (parsed.message?.role !== "assistant") return null;
+    const content = Array.isArray(parsed.message.content)
+      ? parsed.message.content
+        .filter((block) => block?.type === "text")
+        .map((block) => block.text ?? "")
+        .join("")
+      : "";
+    return {
+      type: "assistant",
+      role: "assistant",
+      content
+    };
+  }
+
+  if (parsed.type === "turn_end") {
+    const usage = parsed.message?.usage;
+    if (usage && typeof usage === "object") {
+      const cost = typeof usage.cost === "number"
+        ? usage.cost
+        : typeof usage.cost?.total === "number" ? usage.cost.total : null;
+      return {
+        type: "usage",
+        inputTokens: usage.input ?? usage.inputTokens ?? usage.input_tokens ?? null,
+        outputTokens: usage.output ?? usage.outputTokens ?? usage.output_tokens ?? null,
+        totalTokens: usage.totalTokens ?? usage.total ?? usage.total_tokens ?? null,
+        cost
+      };
+    }
+    return { type: "system", kind: "turn_end" };
+  }
+
+  if (LIFECYCLE_KINDS.has(parsed.type)) {
+    return {
+      type: "system",
+      kind: parsed.type,
+      ...(parsed.reason ? { reason: parsed.reason } : {}),
+      ...(parsed.attempt != null ? { attempt: parsed.attempt } : {})
+    };
+  }
+
+  return {
+    type: "system",
+    kind: parsed.type ?? "unknown"
+  };
+}
+
+export default createExecutionAdapter({
+  id: "pi",
+  label: "Pi",
+  executable: EXECUTABLE,
+  capabilities: {
+    structuredEvents: true,
+    tokens: true,
+    diff: false,
+    cancel: true,
+    transcript: true,
+    reviewCompatible: true
+  },
+  checkAvailability: checkPiAvailability,
+  buildLaunch: buildPiLaunch,
+  parseEventLine: parsePiEventLine
+});

package/src/global/runtime/review/index.js

@@ -0,0 +1,37 @@
+export {
+  REVIEW_SCOPE_MODES, REVIEW_SEVERITIES, REVIEW_STATES, REVIEW_EXIT_CODES, REVIEW_AGENTS,
+  REVIEW_LIMITS, REVIEW_SNAPSHOT_ERROR_CODES, ReviewSnapshotError, resolveReviewScopeMode,
+  createFindingId, canonicalFingerprint, isReviewPrivatePath, isBinaryContent,
+  assertReviewPathSafe, assertWithinReviewLimits, requirePrivateConsent
+} from "./review-types.js";
+export {
+  resolveReviewSnapshot, fingerprintReviewSnapshot, detectReviewSnapshotDrift,
+  readReviewRegularFile
+} from "./review-git.js";
+export {
+  REVIEW_PATCH_ERROR_CODES, filterDiffToAdmittedPaths, buildScopedReviewPatch
+} from "./review-patch.js";
+export {
+  REVIEW_VALIDATION_ERROR_CODES, ReviewValidationError,
+  validateReviewOutput, assertReceiptSecretFree
+} from "./review-validate.js";
+export {
+  assertSafeReviewId, createReviewId, reviewPaths,
+  buildReviewReceipt, saveReviewReceipt, loadReviewReceipt, listReviewReceipts
+} from "./review-receipts.js";
+export {
+  REVIEW_EXEC_ERROR_CODES, REVIEW_EXEC_LIMITS, ReviewExecError,
+  runBoundedProcess, assertBoundedProcessOk
+} from "./review-exec.js";
+export {
+  REVIEW_CODEX_ERROR_CODES, buildCodexReviewArgs, buildCodexCliEnv,
+  buildCodexReviewPrompt, parseCodexReviewJsonl, runCodexReview
+} from "./review-codex.js";
+export {
+  REVIEW_PI_ERROR_CODES, buildPiReviewArgs, buildPiCliEnv,
+  buildPiReviewPrompt, buildPiReviewStdin, parsePiReviewJsonl, runPiReview
+} from "./review-pi.js";
+export {
+  REVIEW_RUNNER_ERROR_CODES, ReviewRunnerError,
+  resolveReviewAgent, resolveReviewExitCode, runReview
+} from "./review-runner.js";