@kal-elsam/kairo-runtime 0.13.0 → 0.14.0

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

@@ -17,23 +17,33 @@ export const COCKPIT_REGIONS = {
 
 export const COCKPIT_NAV = [
   {
-    id: "overview",
-    label: "Overview",
+    id: "home",
+    label: "Home",
     view: ORCHESTRATOR_VIEWS.HOME,
-    description: "Status, next action, activity, alerts, and tokens."
+    description: "What needs you, and what to do about it."
   },
+  {
+    id: "settings",
+    label: "Settings",
+    view: ORCHESTRATOR_VIEWS.PROFILE,
+    description: "Choose agents, connect Obsidian, add integrations."
+  },
+  {
+    id: "history",
+    label: "History",
+    view: ORCHESTRATOR_VIEWS.ACTIVITY,
+    description: "What Kairo changed, and how to undo it."
+  }
+];
+
+/** Destinations reachable via the action palette, not the top nav. */
+export const COCKPIT_SECONDARY = [
   {
     id: "governance",
     label: "Governance",
     view: ORCHESTRATOR_VIEWS.CHANGES,
     description: "Repair drift and apply governed changes."
   },
-  {
-    id: "activity",
-    label: "Activity",
-    view: ORCHESTRATOR_VIEWS.ACTIVITY,
-    description: "Operations, backups, and recovery."
-  },
   {
     id: "orchestration",
     label: "Orchestration",
@@ -45,12 +55,6 @@ export const COCKPIT_NAV = [
     label: "Usage",
     view: ORCHESTRATOR_VIEWS.USAGE,
     description: "Token and context pressure when auditable."
-  },
-  {
-    id: "settings",
-    label: "Settings",
-    view: ORCHESTRATOR_VIEWS.PROFILE,
-    description: "Profile, policy, and guided configuration."
   }
 ];
 
@@ -64,8 +68,8 @@ export function regionsForLayout(layoutMode) {
 
 export function navIndexForView(view, items = COCKPIT_NAV) {
   if (isRunsBranchView(view)) {
-    const orchIndex = items.findIndex((item) => item.id === "orchestration");
-    return orchIndex >= 0 ? orchIndex : 0;
+    const historyIndex = items.findIndex((item) => item.id === "history");
+    return historyIndex >= 0 ? historyIndex : 0;
   }
   const index = items.findIndex((item) => item.view === view);
   return index >= 0 ? index : 0;
@@ -105,6 +109,7 @@ export function resolveNavStatusSummary(item, {
   const backups = snapshot?.backups?.count ?? 0;
 
   switch (item.id) {
+    case "home":
     case "overview":
       return snapshot?.health?.replaceAll("_", " ")
         ?? resolveProjectReadiness({
@@ -114,6 +119,7 @@ export function resolveNavStatusSummary(item, {
         }).label;
     case "governance":
       return changes > 0 ? `${changes} pending` : "Clean";
+    case "history":
     case "activity":
       return backups > 0 ? `${backups} backups` : "No backups";
     case "orchestration":
@@ -174,6 +180,7 @@ export function buildNavModel({
   const mapped = items.map((item, index) => {
     const isSelected = index === navIndex;
     const isCurrent = item.view === currentView
+      || (item.id === "history" && isRunsBranchView(currentView))
       || (item.id === "orchestration" && isRunsBranchView(currentView));
     return {
       ...item,
@@ -185,11 +192,13 @@ export function buildNavModel({
     };
   });
 
+  const explanation = !selected || selected.id === "home" || selected.id === "overview"
+    ? ""
+    : (selected.description ?? "");
+
   return {
     title: "NAVIGATION",
-    explanation: selected
-      ? `${selected.description} (${resolveNavStatusSummary(selected, { dashboard, diagnostics, snapshot })})`
-      : "",
+    explanation,
     items: mapped
   };
 }
@@ -320,7 +329,7 @@ export function buildFooterModel({
   // HOME footer must stay on one line at 80 cols (frame already near 24 rows).
   if (view === ORCHESTRATOR_VIEWS.HOME) {
     return {
-      text: ["↑↓", "Enter", "Space", "R", "?", "/", "Esc"].join(` ${glyphs.bullet} `),
+      text: ["↑↓", "Enter", "Tab", "Space", "R", "?", "/", "Esc"].join(` ${glyphs.bullet} `),
       columns: footerColumns
     };
   }

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

@@ -1,6 +1,8 @@
-import { COCKPIT_NAV } from "./cockpit-models.js";
+import { COCKPIT_NAV, COCKPIT_SECONDARY } from "./cockpit-models.js";
 import { ORCHESTRATOR_VIEWS } from "./orchestrator-state.js";
 
+const PALETTE_NAV_ITEMS = [...COCKPIT_NAV, ...COCKPIT_SECONDARY];
+
 export const PALETTE_KINDS = Object.freeze({
   NAVIGATE: "navigate",
   REFRESH: "refresh",
@@ -12,10 +14,13 @@ const DESTINATION_VIEWS = Object.freeze({
   changes: ORCHESTRATOR_VIEWS.CHANGES,
   governance: ORCHESTRATOR_VIEWS.CHANGES,
   "control-center": ORCHESTRATOR_VIEWS.HOME,
+  home: ORCHESTRATOR_VIEWS.HOME,
   ides: ORCHESTRATOR_VIEWS.IDES,
   modules: ORCHESTRATOR_VIEWS.MODULES,
   activity: ORCHESTRATOR_VIEWS.ACTIVITY,
+  history: ORCHESTRATOR_VIEWS.ACTIVITY,
   profile: ORCHESTRATOR_VIEWS.PROFILE,
+  settings: ORCHESTRATOR_VIEWS.PROFILE,
   runs: ORCHESTRATOR_VIEWS.RUNS,
   orchestration: ORCHESTRATOR_VIEWS.RUNS,
   usage: ORCHESTRATOR_VIEWS.USAGE,
@@ -30,12 +35,12 @@ export function canOpenPalette({ loading = false, busy = false, confirming = fal
   return !loading && !busy && !confirming;
 }
 
-/** Optional CTA + six destinations + Refresh + Help. No write shortcuts. */
+/** Optional CTA + primary/secondary destinations + Refresh + Help. No write shortcuts. */
 export function buildPaletteActions({
   ctaDestination = null,
   ctaTitle = null,
   ctaDetail = null,
-  navItems = COCKPIT_NAV
+  navItems = PALETTE_NAV_ITEMS
 } = {}) {
   const actions = [];
   if (ctaDestination === "setup") {

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

@@ -100,7 +100,8 @@ export function renderCockpitView({
   governanceDetailsOpen = false,
   activityDetailsOpen = false,
   contentFocused = false,
-  homeDir = null
+  homeDir = null,
+  hasGlobalState = false
 }) {
   if (palette) {
     return React.createElement(PalettePanel, { model: palette, colorEnabled });
@@ -112,7 +113,13 @@ export function renderCockpitView({
         detailsOpen: overviewDetailsOpen,
         colorEnabled,
         unicode,
-        layoutMode
+        layoutMode,
+        selectedIndex: listIndex,
+        contentFocused,
+        hasGlobalState,
+        snapshot,
+        diagnostics,
+        dashboard
       });
     case ORCHESTRATOR_VIEWS.USAGE:
       return React.createElement(SemanticUsagePanel, {

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

@@ -46,6 +46,7 @@ import { LAYOUT_MODES } from "./layout.js";
 import { CHANGES_PHASE } from "./cockpit-changes.js";
 import { RECOVERY_PHASE, listRecoverySnapshots } from "./cockpit-recovery.js";
 import { SETTINGS_PHASE } from "./cockpit-settings.js";
+import { buildOverviewButtons, OVERVIEW_BUTTON_COUNT } from "./ux/overview-actions.js";
 
 export function OrchestratorApp({
   homeDir,
@@ -245,7 +246,9 @@ export function OrchestratorApp({
       return;
     }
 
-    const listLength = ui.view === ORCHESTRATOR_VIEWS.RUNS
+    const listLength = ui.view === ORCHESTRATOR_VIEWS.HOME
+      ? OVERVIEW_BUTTON_COUNT
+      : ui.view === ORCHESTRATOR_VIEWS.RUNS
       ? RUNS_HUB_ITEMS.length
       : ui.view === ORCHESTRATOR_VIEWS.ACTIVE_RUNS
         ? (data.dashboard?.activeRuns ?? []).length
@@ -301,6 +304,21 @@ export function OrchestratorApp({
           return;
         }
       }
+      if (routed.type === "enter-home-button") {
+        const buttons = buildOverviewButtons({
+          hasGlobalState,
+          snapshot: data.snapshot,
+          diagnostics: data.diagnostics,
+          dashboard: data.dashboard
+        });
+        const selected = buttons[Math.min(Math.max(0, ui.listIndex), buttons.length - 1)];
+        const intent = selected?.intent ?? null;
+        if (intent === "setup") {
+          finish({ cancelled: false, action: "setup" });
+          return;
+        }
+        if (intent && openDestination(intent)) return;
+      }
       dispatch(routed);
       return;
     }
@@ -583,7 +601,8 @@ export function OrchestratorApp({
         governanceDetailsOpen: ui.governanceDetailsOpen,
         activityDetailsOpen: ui.activityDetailsOpen,
         contentFocused: ui.region === COCKPIT_REGIONS.CONTENT,
-        homeDir
+        homeDir,
+        hasGlobalState
       })
     )
   );

package/src/global/ink/ux/live-overview.js

@@ -1,99 +1,121 @@
 /**
  * Live semantic Overview for Cockpit HOME — product cover.
- * Nav owns the sole focus mark — this panel never renders `>`.
+ * Content owns the button focus mark when region=content.
  * ASCII wordmark only here (wide/compact); minimal is textual.
+ *
+ * Rule: show purpose + two buttons + a few plain-language needs.
+ * Machine/system noise stays out of the first screen (Details only).
  */
 import React from "react";
 import { Box, Text } from "ink";
-import { CONTROL_PLANE_HEALTH } from "../../control-plane-snapshot.js";
+import { DASHBOARD_PURPOSE } from "../../dashboard-guidance.js";
 import { LAYOUT_MODES } from "../layout.js";
-import { COCKPIT_COLORS } from "../theme.js";
+import { COCKPIT_COLORS, resolveGlyphs } from "../theme.js";
 import {
   overviewBrandTitle,
   shouldShowWordmark,
   wordmarkLines
 } from "../brand/wordmark.js";
 import { ActionList, Callout, Details } from "./semantic.js";
+import {
+  humanizeDestination,
+  humanizeHealthTitle,
+  humanizePrimary,
+  mapHealthTone,
+  partitionCompanionLines
+} from "./overview-needs.js";
+import { buildOverviewButtons, OVERVIEW_BUTTON_COUNT } from "./overview-actions.js";
 
-const DESTINATION_LABELS = {
-  setup: "Setup",
-  changes: "Governance",
-  ides: "Agents",
-  runs: "Orchestration",
-  "control-center": "Overview",
-  activity: "Activity",
-  usage: "Usage",
-  profile: "Settings"
-};
-
-export function mapHealthTone(kind) {
-  switch (kind) {
-    case CONTROL_PLANE_HEALTH.CHECK_FAILED:
-      return "danger";
-    case CONTROL_PLANE_HEALTH.ACTION_REQUIRED:
-    case CONTROL_PLANE_HEALTH.NOT_CONFIGURED:
-    case CONTROL_PLANE_HEALTH.HEALTHY_WITH_NOTES:
-      return "warn";
-    case CONTROL_PLANE_HEALTH.HEALTHY:
-      return "ready";
-    default:
-      return "warn";
-  }
-}
+export {
+  humanizeCompanionNeed,
+  humanizeHealthTitle,
+  humanizePrimary,
+  mapHealthTone,
+  partitionCompanionLines
+} from "./overview-needs.js";
 
-function humanizeDestination(destination) {
-  if (!destination) return null;
-  return DESTINATION_LABELS[destination] ?? null;
-}
+export { buildOverviewButtons, OVERVIEW_BUTTON_COUNT } from "./overview-actions.js";
 
-/** Safe Details lines only — never invent paths/IDs; honest empty when none. */
-export function buildOverviewDetails(model = {}) {
+/** Safe Details lines — leftovers + raw signals; never invent paths/IDs. */
+export function buildOverviewDetails(model = {}, companionRest = []) {
   const lines = [];
   const next = model.nextAction ?? model.cta ?? {};
   const dest = humanizeDestination(next.destination);
-  if (dest) lines.push(`Next destination · ${dest}`);
-  if (typeof model.alerts?.count === "number") {
+  if (dest) lines.push(`Opens · ${dest}`);
+  if (typeof model.alerts?.count === "number" && model.alerts.count > 0) {
     lines.push(`Open alerts · ${model.alerts.count}`);
   }
+  const tokens = model.tokens?.headline;
+  if (typeof tokens === "string" && tokens && !/unavailable/i.test(tokens)) {
+    lines.push(`Tokens · ${tokens}`);
+  }
   const secondary = model.companionNextAction;
   if (secondary?.title && secondary.kind !== "idle") {
     lines.push(`Companion · ${secondary.title}`);
   }
-  if (lines.length === 0) return ["No extra evidence beyond the metrics above."];
+  for (const line of companionRest) {
+    if (typeof line === "string" && line.trim()) lines.push(line);
+  }
+  if (lines.length === 0) return ["Nothing else to show right now."];
   return lines;
 }
 
 /**
  * Pure adapter: buildControlCenterModel → semantic overview props.
- * Callout / CTA / metrics never include paths or IDs.
- * Primary action is always governance CTA — companion is secondary metrics/details only.
+ * First screen = purpose + two buttons + plain needs. Machine noise → Details.
  */
-export function adaptControlCenterToOverview(model = {}) {
+export function adaptControlCenterToOverview(model = {}, options = {}) {
   const status = model.status ?? model.health ?? {};
   const next = model.nextAction ?? model.cta ?? {};
-  const companionMetrics = (model.companion?.lines ?? []).map((label, i) => ({
-    id: `companion-${i}`,
-    label
-  }));
+  const { needs, rest } = partitionCompanionLines(model.companion?.lines ?? []);
+  const primary = humanizePrimary(next);
+  const buttons = buildOverviewButtons({
+    hasGlobalState: options.hasGlobalState,
+    snapshot: options.snapshot,
+    diagnostics: options.diagnostics,
+    dashboard: options.dashboard
+  });
+
+  const activity = model.activity?.headline;
+  const metrics = [];
+  const hasUsefulActivity = typeof activity === "string"
+    && activity
+    && activity !== "Idle"
+    && activity !== "No activity yet";
+  if (hasUsefulActivity) {
+    metrics.push({ id: "activity", label: `Last activity · ${activity.replace(/^Last ·\s*/, "")}` });
+  }
+  for (let i = 0; i < needs.length; i += 1) {
+    metrics.push({ id: `need-${i}`, label: needs[i] });
+  }
+  if ((model.alerts?.count ?? 0) > 0) {
+    metrics.push({
+      id: "alerts",
+      label: `Alerts · ${model.alerts.headline ?? `${model.alerts.count} open`}`
+    });
+  }
+  if (rest.length > 0) {
+    metrics.push({
+      id: "more",
+      label: `${rest.length} more in Details · Space`
+    });
+  }
+  if (metrics.length === 0) {
+    metrics.push({ id: "quiet", label: "Nothing else needs you right now" });
+  }
+
   return {
     title: model.title ?? "Overview",
+    purpose: DASHBOARD_PURPOSE,
     callout: {
       tone: mapHealthTone(status.kind),
-      title: status.label ?? "Unknown",
+      title: humanizeHealthTitle(status.kind, status.label),
       body: status.summaryLine ?? ""
     },
-    primary: {
-      label: next.actionTitle ?? "Review control plane",
-      detail: next.actionDetail || null,
-      hint: next.enterHint ?? null
-    },
-    metrics: [
-      { id: "activity", label: `Activity · ${model.activity?.headline ?? "Idle"}` },
-      { id: "alerts", label: `Alerts · ${model.alerts?.headline ?? "Alert data unavailable"}` },
-      { id: "tokens", label: `Tokens · ${model.tokens?.headline ?? "Data unavailable"}` },
-      ...companionMetrics
-    ],
-    details: buildOverviewDetails(model)
+    primary,
+    buttons,
+    metrics,
+    details: buildOverviewDetails(model, rest)
   };
 }
 
@@ -124,14 +146,30 @@ export function SemanticOverviewPanel({
   detailsOpen = false,
   colorEnabled = true,
   unicode = true,
-  layoutMode = LAYOUT_MODES.COMPACT
+  layoutMode = LAYOUT_MODES.COMPACT,
+  selectedIndex = 0,
+  contentFocused = false,
+  hasGlobalState = false,
+  snapshot = null,
+  diagnostics = null,
+  dashboard = null
 }) {
-  const view = adaptControlCenterToOverview(model);
+  const view = adaptControlCenterToOverview(model, {
+    hasGlobalState,
+    snapshot,
+    diagnostics,
+    dashboard
+  });
   const showArt = shouldShowWordmark(layoutMode);
   const brandTitle = overviewBrandTitle(layoutMode);
   const isWide = layoutMode === LAYOUT_MODES.WIDE;
   const mark = renderWordmark({ layoutMode, colorEnabled, unicode });
   const status = renderCallout(view, colorEnabled);
+  const safeIndex = Math.min(
+    Math.max(0, selectedIndex),
+    Math.max(0, view.buttons.length - 1)
+  );
+  const glyphs = resolveGlyphs(unicode);
 
   const hero = showArt
     ? (isWide
@@ -150,19 +188,29 @@ export function SemanticOverviewPanel({
 
   return React.createElement(Box, { flexDirection: "column" },
     hero,
+    React.createElement(Text, {
+      color: colorEnabled ? COCKPIT_COLORS.muted : undefined
+    }, view.purpose),
     React.createElement(Box, { marginTop: 1, flexDirection: "column" },
-      React.createElement(Text, {
-        bold: true,
-        color: colorEnabled ? COCKPIT_COLORS.interactive : undefined
-      }, view.primary.label),
-      view.primary.detail
-        ? React.createElement(Text, null, view.primary.detail)
-        : null,
-      view.primary.hint
-        ? React.createElement(Text, {
-          color: colorEnabled ? COCKPIT_COLORS.muted : undefined
-        }, view.primary.hint)
-        : null
+      ...view.buttons.map((button, index) => {
+        const selected = index === safeIndex;
+        const focused = contentFocused && selected;
+        return React.createElement(Box, {
+          key: button.id,
+          flexDirection: "column",
+          marginBottom: index === view.buttons.length - 1 ? 0 : 1
+        },
+          React.createElement(Text, {
+            bold: true,
+            color: focused && colorEnabled ? COCKPIT_COLORS.interactive : undefined
+          }, `${focused ? glyphs.focus : " "} ${button.label}`),
+          button.detail
+            ? React.createElement(Text, {
+              color: colorEnabled ? COCKPIT_COLORS.muted : undefined
+            }, `  ${button.detail}`)
+            : null
+        );
+      })
     ),
     React.createElement(Box, { marginTop: 1, flexDirection: "column" },
       React.createElement(ActionList, {
@@ -175,7 +223,7 @@ export function SemanticOverviewPanel({
     ),
     React.createElement(Details, {
       open: detailsOpen,
-      summary: "Details",
+      summary: "More info",
       lines: view.details,
       colorEnabled,
       focused: false,

package/src/global/ink/ux/overview-actions.js

@@ -0,0 +1,80 @@
+/**
+ * Two explicit Home buttons — prepare + configure.
+ * No writes here: intents only open existing consent-gated flows.
+ */
+
+export const OVERVIEW_BUTTON_COUNT = 2;
+
+function changeCount(snapshot) {
+  if (!snapshot?.diff?.hasChanges) return 0;
+  return snapshot.diff.changeCount
+    ?? snapshot.diff.changes?.length
+    ?? 0;
+}
+
+function detectedAgentCount({ snapshot = null, diagnostics = null, dashboard = null } = {}) {
+  if (Number.isFinite(snapshot?.coverage?.detectedAgents)) {
+    return snapshot.coverage.detectedAgents;
+  }
+  if (Number.isFinite(diagnostics?.diagnostics?.detected)) {
+    return diagnostics.diagnostics.detected;
+  }
+  return (dashboard?.providers ?? []).filter((entry) => entry?.available).length;
+}
+
+function buildPrepareButton({
+  hasGlobalState = false,
+  snapshot = null,
+  diagnostics = null,
+  dashboard = null
+} = {}) {
+  const detected = detectedAgentCount({ snapshot, diagnostics, dashboard });
+  const needsSetup = hasGlobalState === false || detected === 0;
+  if (needsSetup) {
+    return {
+      id: "prepare",
+      label: "Set up Kairo",
+      detail: "Detect your agents and install what is missing.",
+      intent: "setup"
+    };
+  }
+
+  const pending = changeCount(snapshot);
+  if (pending > 0) {
+    return {
+      id: "prepare",
+      label: `Repair ${pending} change${pending === 1 ? "" : "s"}`,
+      detail: "You will see the exact plan before anything is written.",
+      intent: "governance"
+    };
+  }
+
+  return {
+    id: "prepare",
+    label: "Everything is ready",
+    detail: "Open History to see what changed, or Configure to adjust.",
+    intent: "history"
+  };
+}
+
+const CONFIGURE_BUTTON = Object.freeze({
+  id: "configure",
+  label: "Configure",
+  detail: "Agents, Obsidian vault, integrations.",
+  intent: "settings"
+});
+
+/**
+ * Exactly two buttons for Home. First button changes face by state.
+ */
+export function buildOverviewButtons({
+  hasGlobalState = false,
+  snapshot = null,
+  diagnostics = null,
+  dashboard = null
+} = {}) {
+  return [
+    buildPrepareButton({ hasGlobalState, snapshot, diagnostics, dashboard }),
+    { ...CONFIGURE_BUTTON }
+  ];
+}