@kal-elsam/kairo-runtime 0.2.2 → 0.3.0

package/README.md

@@ -24,13 +24,37 @@ commands) without depending on Pi as a runtime or adding a Pi adapter.
 
 ## Quick start
 
-Recommended entry — run Kairo Runtime in your terminal (interactive setup wizard in a TTY):
+Recommended entry — run Kairo Runtime in your terminal:
 
 ```bash
 npx @kal-elsam/kairo-runtime
+# or, after a global install:
+kairo
 ```
 
-Preview without writing anything:
+**First run** (no `~/.harness/state.json`): interactive onboarding → safe diagnosis →
+setup with confirmation → full-screen operations cockpit.
+
+**Later runs** (state present): full-screen cockpit with mission control (recommended
+action), navigation, and a system strip. Layout adapts to terminal size:
+
+| Mode | Size | Layout |
+|------|------|--------|
+| Wide | ≥100 cols × ≥28 rows | Nav + content + system |
+| Compact | ≥72×20 | Nav + content |
+| Minimal | 60–71 cols or short height | Single panel + nav header |
+| Below gate | <60 cols | Explicit TTY fallback (Ink disabled) |
+
+Keys: `↑↓` navigate · `Tab` region · `Enter` open · `R` refresh · `C` cancel run ·
+`?` help · `Esc` back (exit only from Home).
+
+Respects `NO_COLOR`, `HARNESS_ASCII=1`, and `HARNESS_INK=0`. Status is always labeled
+in text, never color alone.
+
+Explicit commands and setup flags keep their current behavior (`kairo setup`,
+`kairo --dry-run`, `kairo shell`, non-TTY scripts, etc.).
+
+Preview setup without writing anything:
 
 ```bash
 npx @kal-elsam/kairo-runtime --dry-run

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Gemini, Copilot, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",
@@ -33,6 +33,7 @@
     "doctor": "node ./bin/kairo.js doctor",
     "smoke": "bash scripts/smoke-test.sh",
     "ux:smoke": "bash scripts/ux-smoke-test.sh",
+    "smoke:cockpit": "bash scripts/cockpit-smoke-test.sh",
     "smoke:registry": "bash scripts/registry-smoke-test.sh",
     "smoke:installer": "bash scripts/installer-smoke-test.sh",
     "smoke:bridge": "bash scripts/bridge-smoke-test.sh",
@@ -59,6 +60,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
+    "ansi-escapes": "^7.3.0",
     "ink": "^5.2.1",
     "react": "^18.3.1"
   }

package/scripts/cockpit-smoke-test.sh

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Cockpit smoke — layout/capabilities + package wiring (no PTY required).
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+echo "Kairo cockpit smoke"
+node "$ROOT/scripts/cockpit-smoke.mjs"
+
+node --test \
+  test/fullscreen-session.test.js \
+  test/layout.test.js \
+  test/terminal-capabilities.test.js \
+  test/cockpit-models.test.js \
+  test/cockpit-controller.test.js \
+  test/cockpit-frame.test.js
+
+echo "Kairo cockpit smoke passed"

package/scripts/cockpit-smoke.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveLayoutMode, LAYOUT_MODES } from "../src/global/ink/layout.js";
+import { resolveTerminalCapabilities } from "../src/global/ink/terminal-capabilities.js";
+import { createFullscreenSession } from "../src/global/ink/fullscreen-session.js";
+import { buildTopBarModel, buildHomeMissionModel } from "../src/global/ink/cockpit-models.js";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const require = createRequire(import.meta.url);
+const pkg = require(join(root, "package.json"));
+
+assert.equal(pkg.version, "0.3.0");
+assert.ok(pkg.dependencies["ansi-escapes"]);
+
+assert.equal(resolveLayoutMode({ columns: 120, rows: 40 }), LAYOUT_MODES.WIDE);
+assert.equal(resolveLayoutMode({ columns: 80, rows: 24 }), LAYOUT_MODES.COMPACT);
+assert.equal(resolveLayoutMode({ columns: 65, rows: 24 }), LAYOUT_MODES.MINIMAL);
+assert.equal(resolveLayoutMode({ columns: 50, rows: 24 }), null);
+
+const caps = resolveTerminalCapabilities({
+  columns: 80,
+  rows: 24,
+  isTTY: true,
+  term: "xterm-256color",
+  env: { NO_COLOR: "1" }
+});
+assert.equal(caps.color, false);
+assert.equal(caps.canUseInk, true);
+
+const session = createFullscreenSession({
+  stdout: { isTTY: true, write: () => true },
+  processRef: { on() {}, removeListener() {}, exit() {} },
+  onSignal: () => {}
+});
+assert.equal(session.enter(), true);
+assert.equal(session.leave(), true);
+assert.equal(session.leave(), false);
+
+const top = buildTopBarModel({ projectName: "smoke" });
+assert.match(top.status, /ONLINE|Offline/);
+const mission = buildHomeMissionModel({
+  hasGlobalState: false,
+  diagnostics: { diagnostics: { detected: 0 } },
+  dashboard: { providers: [], recentRuns: [] }
+});
+assert.match(mission.title, /MISSION CONTROL/);
+
+console.log("cockpit smoke OK");

package/src/cli.js

@@ -42,6 +42,11 @@ import {
   resolveSuggestedInvocation
 } from "./global/brand/cli.js";
 import { BRAND } from "./global/brand/index.js";
+import {
+  INITIAL_EXPERIENCE,
+  hasConfiguredGlobalState,
+  resolveInitialExperience
+} from "./global/initial-experience.js";
 
 export { resolveSuggestedInvocation };
 
@@ -50,7 +55,7 @@ const packageRoot = resolve(__dirname, "..");
 const SCOPES = new Set(["agent-global", "workspace"]);
 
 export async function runCli(argv) {
-  const { command, options } = parseArgs(argv);
+  const { command, options, isImplicitCommand } = parseArgs(argv);
   maybeWarnLegacyCli(process.argv, { json: options.json });
 
   if (options.help || command === "help") {
@@ -69,14 +74,22 @@ export async function runCli(argv) {
   const invoke = resolveSuggestedInvocation(packageManifest.name);
 
   switch (command) {
-    case "shell":
+    case "shell": {
+      const homeDir = resolveHomeDir();
+      const resolvedMode = resolveInitialExperience({
+        interactive: optionsWithPolicy.interactive,
+        isImplicitCommand,
+        hasGlobalState: hasConfiguredGlobalState(homeDir)
+      });
       await runOrchestratorShell({
         packageRoot,
         packageManifest,
         workspaceRoot: optionsWithPolicy.cwd,
-        interactive: optionsWithPolicy.interactive
+        interactive: optionsWithPolicy.interactive,
+        initialMode: resolvedMode ?? INITIAL_EXPERIENCE.DASHBOARD
       });
       return;
+    }
     case "orchestrator":
       await runOrchestratorDiagnostics({
         homeDir: resolveHomeDir(),
@@ -468,7 +481,7 @@ export function parseArgs(argv) {
     options.task = args.join(" ").trim();
   }
 
-  return { command, options };
+  return { command, options, isImplicitCommand: implicitCommand };
 }
 
 function parseComponentsAction(args, options) {
@@ -683,10 +696,11 @@ sections, components, backups, and drift repair under ~/.harness.
 Bootstrap: see README.md (curl install.sh or npx ${PACKAGE_NAME}).
 
 Usage:
-  ${cli}                              Interactive orchestrator shell (TTY)
+  ${cli}                              First run: onboarding → setup → cockpit (TTY).
+                                      Later: full-screen cockpit (wide/compact/minimal).
   ${cli} --dry-run                      Setup dry-run (scriptable)
   ${cli} --version
-  ${cli} shell                          Operations dashboard (TTY)
+  ${cli} shell                          Operations cockpit (TTY)
   ${cli} run --agent <id> --task "..." [--model <name>] [--cwd <dir>] [--permissions force] [--capture-transcript] [--follow] [--no-wait] [--json]
   ${cli} runs list [--json] [--limit <n>] [--active-only]
   ${cli} runs show <runId> [--json] [--limit <n>] [--follow]
@@ -727,7 +741,9 @@ Scopes:
                           Explicit --scope=workspace only.
 
 Commands:
-  shell      Operations dashboard (TTY). Bare ${cli} opens this in TTY sessions.
+  shell      Operations cockpit (TTY). Bare ${cli} opens onboarding when ~/.harness/state.json
+             is missing, otherwise the cockpit. Explicit ${cli} shell always opens the cockpit.
+             Keys: ↑↓ · Tab region · Enter · R refresh · C cancel · ? help · Esc back/exit.
   run        Launch a managed agent run with local audit trail.
   runs       List, inspect, or cancel agent runs under ~/.harness/runs/.
   orchestrator  Read-only capability registry diagnostics (--json supported).

package/src/global/brand/index.js

@@ -70,6 +70,16 @@ export const WIZARD_COPY = {
   coreOnlyLabel: "Core only (no components)"
 };
 
+/** First-run framing reused by onboarding → setup. */
+export const ONBOARDING_COPY = {
+  welcomeTitle: `Welcome to ${BRAND.displayName}`,
+  purpose:
+    `${BRAND.displayName} detects, configures, and coordinates the local agents you already use.`,
+  safety:
+    "Diagnosis is read-only. Nothing is modified until you confirm a plan.",
+  continueHint: "Press Enter to diagnose and configure · Esc to exit"
+};
+
 export function getAgentLabel(agentId) {
   return AGENT_LABELS[agentId] ?? agentId;
 }

package/src/global/dashboard-guidance.js

@@ -0,0 +1,66 @@
+import { formatCliCommand } from "./brand/cli.js";
+
+export const DASHBOARD_PURPOSE =
+  "Detects, configures, and coordinates local AI agents — no changes without confirmation.";
+
+export const NEXT_STEP_KINDS = {
+  CONFIGURE: "configure",
+  ENABLE_INTELLIGENCE: "enable_intelligence",
+  LAUNCH: "launch",
+  REVIEW: "review"
+};
+
+export function formatDashboardPurpose() {
+  return DASHBOARD_PURPOSE;
+}
+
+/**
+ * Contextual next step from existing diagnostics + dashboard snapshot.
+ * Priority: configure → review problems → enable intelligence → launch.
+ */
+export function resolveDashboardRecommendation({
+  hasGlobalState = false,
+  diagnostics = null,
+  dashboard = null
+} = {}) {
+  const summary = diagnostics?.diagnostics ?? { detected: 0, errors: 0 };
+  const intelligence = diagnostics?.intelligence?.summary;
+  const launchableCount = (dashboard?.providers ?? []).filter((entry) => entry.launchable).length;
+  const hasErrors = (summary.errors ?? 0) > 0;
+  const hasProblemRecommendation = (diagnostics?.recommendations ?? []).some((line) =>
+    /error|fix|drift|not detected|failed|problem/i.test(line)
+  );
+
+  if (!hasGlobalState || (summary.detected ?? 0) === 0) {
+    return {
+      kind: NEXT_STEP_KINDS.CONFIGURE,
+      message: `Configure the local environment with ${formatCliCommand("setup")}.`
+    };
+  }
+
+  if (hasErrors || hasProblemRecommendation) {
+    return {
+      kind: NEXT_STEP_KINDS.REVIEW,
+      message: "Review diagnostics for problems before launching a run."
+    };
+  }
+
+  if (!intelligence?.localAvailable && !intelligence?.cloudAuthenticated) {
+    return {
+      kind: NEXT_STEP_KINDS.ENABLE_INTELLIGENCE,
+      message: "Enable intelligence: start Ollama or set OPENROUTER_API_KEY, then retry."
+    };
+  }
+
+  if (launchableCount > 0) {
+    return {
+      kind: NEXT_STEP_KINDS.LAUNCH,
+      message: "Launch a supervised run from the menu or with kairo run."
+    };
+  }
+
+  return {
+    kind: NEXT_STEP_KINDS.REVIEW,
+    message: "Review diagnostics for problems before launching a run."
+  };
+}

package/src/global/initial-experience.js

@@ -0,0 +1,34 @@
+import { existsSync } from "node:fs";
+import { harnessHomePaths } from "./paths.js";
+
+export const INITIAL_EXPERIENCE = {
+  ONBOARDING: "onboarding",
+  DASHBOARD: "dashboard"
+};
+
+/**
+ * First-run marker is ~/.harness/state.json only.
+ * profile.json does not participate in this decision.
+ */
+export function hasConfiguredGlobalState(homeDir) {
+  return existsSync(harnessHomePaths(homeDir).statePath);
+}
+
+/**
+ * Pure resolver for the interactive bare-entry experience.
+ * Returns null when CLI should keep existing non-onboarding paths
+ * (non-TTY, explicit commands, setup flags already routed elsewhere).
+ */
+export function resolveInitialExperience({
+  interactive = false,
+  isImplicitCommand = false,
+  hasGlobalState = false
+} = {}) {
+  if (!interactive || !isImplicitCommand) {
+    return null;
+  }
+
+  return hasGlobalState
+    ? INITIAL_EXPERIENCE.DASHBOARD
+    : INITIAL_EXPERIENCE.ONBOARDING;
+}

package/src/global/ink/cockpit/primitives.js

@@ -0,0 +1,131 @@
+import React from "react";
+import { Box, Text } from "ink";
+import { COCKPIT_COLORS, statusColor } from "../theme.js";
+
+export function CockpitBadge({ label, kind = "ready", colorEnabled = true }) {
+  return React.createElement(Text, {
+    color: statusColor(kind, { colorEnabled })
+  }, label);
+}
+
+export function CockpitEmptyState({ title, message, hint }) {
+  return React.createElement(Box, { flexDirection: "column", marginY: 1 },
+    title && React.createElement(Text, { bold: true, color: COCKPIT_COLORS.secondary }, title),
+    message && React.createElement(Text, null, message),
+    hint && React.createElement(Text, { color: COCKPIT_COLORS.muted }, hint)
+  );
+}
+
+export function CockpitPanel({ title, focused = false, width, children }) {
+  return React.createElement(Box, {
+    flexDirection: "column",
+    width,
+    borderStyle: "single",
+    borderColor: focused ? COCKPIT_COLORS.primary : COCKPIT_COLORS.muted,
+    paddingX: 1,
+    flexGrow: 1
+  },
+    title && React.createElement(Text, {
+      bold: true,
+      color: focused ? COCKPIT_COLORS.primary : COCKPIT_COLORS.secondary
+    }, title),
+    children
+  );
+}
+
+export function CockpitTopBar({ model, colorEnabled = true }) {
+  return React.createElement(Box, { justifyContent: "space-between", width: "100%" },
+    React.createElement(Text, {
+      bold: true,
+      color: colorEnabled ? COCKPIT_COLORS.primary : undefined
+    }, `╭─ ${model.brand} ─ ${model.status}`),
+    React.createElement(Text, {
+      color: colorEnabled ? COCKPIT_COLORS.muted : undefined
+    }, `${model.projectLabel} ─╮`)
+  );
+}
+
+export function CockpitNav({ model, colorEnabled = true }) {
+  return React.createElement(Box, { flexDirection: "column" },
+    model.items.map((item) =>
+      React.createElement(Text, {
+        key: item.id,
+        bold: item.focused || item.selected,
+        color: item.focused
+          ? (colorEnabled ? COCKPIT_COLORS.primary : undefined)
+          : item.selected
+            ? (colorEnabled ? COCKPIT_COLORS.secondary : undefined)
+            : undefined
+      }, `${item.marker} ${item.label}`)
+    )
+  );
+}
+
+export function CockpitSystemStrip({ model, colorEnabled = true }) {
+  return React.createElement(Box, { flexDirection: "column" },
+    model.rows.map((row) =>
+      React.createElement(Text, { key: row.key },
+        React.createElement(Text, { color: COCKPIT_COLORS.muted }, `${row.key.padEnd(7)}`),
+        React.createElement(CockpitBadge, {
+          label: row.value,
+          kind: row.kind,
+          colorEnabled
+        })
+      )
+    )
+  );
+}
+
+export function CockpitFooter({ model }) {
+  return React.createElement(Box, { flexDirection: "column" },
+    React.createElement(Text, { color: COCKPIT_COLORS.muted },
+      `├${"─".repeat(62)}┤`
+    ),
+    React.createElement(Text, { color: COCKPIT_COLORS.muted }, `│ ${model.text}`),
+    React.createElement(Text, { color: COCKPIT_COLORS.muted },
+      `╰${"─".repeat(62)}╯`
+    )
+  );
+}
+
+export function CockpitShell({
+  topBar,
+  footer,
+  layoutMode,
+  nav,
+  system,
+  navFocused,
+  contentFocused,
+  systemFocused,
+  colorEnabled = true,
+  children
+}) {
+  const showNav = layoutMode === "wide" || layoutMode === "compact";
+  const showSystem = layoutMode === "wide";
+
+  return React.createElement(Box, { flexDirection: "column", width: "100%" },
+    React.createElement(CockpitTopBar, { model: topBar, colorEnabled }),
+    layoutMode === "minimal" && nav && React.createElement(Box, { marginY: 0 },
+      React.createElement(Text, { color: COCKPIT_COLORS.muted }, "Nav: "),
+      React.createElement(CockpitNav, { model: nav, colorEnabled })
+    ),
+    React.createElement(Box, { flexDirection: "row", width: "100%" },
+      showNav && React.createElement(CockpitPanel, {
+        title: nav?.title ?? "NAVIGATION",
+        focused: navFocused,
+        width: 22
+      }, React.createElement(CockpitNav, { model: nav, colorEnabled })),
+      React.createElement(CockpitPanel, {
+        title: undefined,
+        focused: contentFocused,
+        width: showSystem ? 48 : showNav ? 56 : "100%"
+      }, children),
+      showSystem && React.createElement(CockpitPanel, {
+        title: system?.title ?? "SYSTEM",
+        focused: systemFocused,
+        width: 20
+      }, React.createElement(CockpitSystemStrip, { model: system, colorEnabled }))
+    ),
+    React.createElement(CockpitFooter, { model: footer })
+  );
+}

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

@@ -0,0 +1,131 @@
+import { COCKPIT_NAV, COCKPIT_REGIONS, regionsForLayout } from "./cockpit-models.js";
+import { ORCHESTRATOR_VIEWS } from "./orchestrator-state.js";
+import { LAYOUT_MODES } from "./layout.js";
+
+/**
+ * Pure cockpit focus / navigation reducer — no I/O, no React.
+ */
+
+export function createCockpitUiState({
+  layoutMode = LAYOUT_MODES.COMPACT,
+  view = ORCHESTRATOR_VIEWS.HOME,
+  region = COCKPIT_REGIONS.NAV,
+  navIndex = 0,
+  listIndex = 0,
+  helpOpen = false
+} = {}) {
+  const regions = regionsForLayout(layoutMode);
+  const safeRegion = regions.includes(region) ? region : regions[0];
+  return {
+    layoutMode,
+    view,
+    region: safeRegion,
+    navIndex: clamp(navIndex, 0, COCKPIT_NAV.length - 1),
+    listIndex: Math.max(0, listIndex),
+    helpOpen,
+    shouldExit: false
+  };
+}
+
+export function reduceCockpitUi(state, action) {
+  switch (action.type) {
+    case "resize": {
+      const regions = regionsForLayout(action.layoutMode);
+      const region = regions.includes(state.region) ? state.region : regions[0];
+      return { ...state, layoutMode: action.layoutMode, region };
+    }
+    case "tab": {
+      const regions = regionsForLayout(state.layoutMode);
+      if (regions.length < 2) return state;
+      const index = regions.indexOf(state.region);
+      const next = regions[(index + 1) % regions.length];
+      return { ...state, region: next };
+    }
+    case "arrow": {
+      if (state.helpOpen) return state;
+      if (state.region === COCKPIT_REGIONS.SYSTEM) return state;
+
+      const navigatesNav = state.region === COCKPIT_REGIONS.NAV
+        || (state.view === ORCHESTRATOR_VIEWS.HOME
+          && state.layoutMode === LAYOUT_MODES.MINIMAL);
+
+      if (navigatesNav) {
+        const delta = action.direction === "up" ? -1 : 1;
+        return {
+          ...state,
+          navIndex: clamp(state.navIndex + delta, 0, COCKPIT_NAV.length - 1)
+        };
+      }
+
+      const delta = action.direction === "up" ? -1 : 1;
+      const max = Math.max(0, (action.listLength ?? 1) - 1);
+      return { ...state, listIndex: clamp(state.listIndex + delta, 0, max) };
+    }
+    case "enter-nav": {
+      const item = COCKPIT_NAV[state.navIndex];
+      if (!item) return state;
+      if (item.view === ORCHESTRATOR_VIEWS.HOME) {
+        return {
+          ...state,
+          view: ORCHESTRATOR_VIEWS.HOME,
+          listIndex: 0,
+          region: COCKPIT_REGIONS.CONTENT
+        };
+      }
+      return {
+        ...state,
+        view: item.view,
+        listIndex: 0,
+        region: COCKPIT_REGIONS.CONTENT,
+        helpOpen: false
+      };
+    }
+    case "set-view":
+      return {
+        ...state,
+        view: action.view,
+        listIndex: 0,
+        region: action.region ?? COCKPIT_REGIONS.CONTENT
+      };
+    case "toggle-help":
+      if (state.helpOpen) {
+        return {
+          ...state,
+          helpOpen: false,
+          view: state.view === ORCHESTRATOR_VIEWS.HELP
+            ? ORCHESTRATOR_VIEWS.HOME
+            : state.view
+        };
+      }
+      return { ...state, helpOpen: true, view: ORCHESTRATOR_VIEWS.HELP };
+    case "escape": {
+      if (state.helpOpen) {
+        return { ...state, helpOpen: false, view: ORCHESTRATOR_VIEWS.HOME };
+      }
+      if (state.view !== ORCHESTRATOR_VIEWS.HOME) {
+        const regions = regionsForLayout(state.layoutMode);
+        return {
+          ...state,
+          view: ORCHESTRATOR_VIEWS.HOME,
+          listIndex: 0,
+          region: regions.includes(COCKPIT_REGIONS.NAV)
+            ? COCKPIT_REGIONS.NAV
+            : COCKPIT_REGIONS.CONTENT
+        };
+      }
+      return { ...state, shouldExit: true };
+    }
+    case "clear-exit":
+      return { ...state, shouldExit: false };
+    default:
+      return state;
+  }
+}
+
+export function resolveNavAction(navIndex) {
+  return COCKPIT_NAV[navIndex] ?? null;
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}