@kal-elsam/kairo-runtime 0.2.3 → 0.3.1

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

@@ -0,0 +1,180 @@
+import { LAYOUT_MODES } from "./layout.js";
+import { ORCHESTRATOR_VIEWS } from "./orchestrator-state.js";
+import { resolveDashboardRecommendation } from "../dashboard-guidance.js";
+import { STATUS_LABELS, resolveGlyphs } from "./theme.js";
+import { windowList } from "./list-window.js";
+import { resolveListLimit } from "./layout.js";
+
+export const COCKPIT_REGIONS = {
+  NAV: "nav",
+  CONTENT: "content",
+  SYSTEM: "system"
+};
+
+export const COCKPIT_NAV = [
+  { id: "overview", label: "Overview", view: ORCHESTRATOR_VIEWS.HOME },
+  { id: "active", label: "Active runs", view: ORCHESTRATOR_VIEWS.ACTIVE_RUNS },
+  { id: "recent", label: "Recent runs", view: ORCHESTRATOR_VIEWS.RECENT_RUNS },
+  { id: "providers", label: "Providers", view: ORCHESTRATOR_VIEWS.PROVIDERS },
+  { id: "launch", label: "Launch run", view: ORCHESTRATOR_VIEWS.LAUNCH, action: "launch" },
+  { id: "diagnostics", label: "Diagnostics", view: ORCHESTRATOR_VIEWS.DIAGNOSTICS }
+];
+
+export function regionsForLayout(layoutMode) {
+  if (layoutMode === LAYOUT_MODES.WIDE) {
+    return [COCKPIT_REGIONS.NAV, COCKPIT_REGIONS.CONTENT, COCKPIT_REGIONS.SYSTEM];
+  }
+  if (layoutMode === LAYOUT_MODES.COMPACT) {
+    return [COCKPIT_REGIONS.NAV, COCKPIT_REGIONS.CONTENT];
+  }
+  return [COCKPIT_REGIONS.CONTENT];
+}
+
+export function buildTopBarModel({
+  projectName = "project",
+  systemOnline = true,
+  unicode = true
+} = {}) {
+  const glyphs = resolveGlyphs(unicode);
+  const status = systemOnline ? STATUS_LABELS.online : STATUS_LABELS.offline;
+  return {
+    brand: "KAIRO",
+    status,
+    statusKind: systemOnline ? "online" : "offline",
+    projectLabel: `Project: ${projectName}`,
+    separator: glyphs.bullet
+  };
+}
+
+export function buildNavModel({
+  navIndex = 0,
+  focused = false,
+  unicode = true,
+  items = COCKPIT_NAV
+} = {}) {
+  const glyphs = resolveGlyphs(unicode);
+  return {
+    title: "NAVIGATION",
+    items: items.map((item, index) => ({
+      ...item,
+      marker: index === navIndex ? glyphs.focus : " ",
+      selected: index === navIndex,
+      focused: focused && index === navIndex
+    }))
+  };
+}
+
+export function buildSystemStripModel({
+  dashboard = null,
+  diagnostics = null,
+  healthKind = "ready"
+} = {}) {
+  const agentsDetected = diagnostics?.diagnostics?.detected
+    ?? (dashboard?.providers ?? []).filter((p) => p.available).length;
+  const agentsTotal = diagnostics?.capabilities?.length
+    ?? dashboard?.providers?.length
+    ?? 0;
+  const activeRuns = dashboard?.activeRuns?.length ?? 0;
+  const intelligence = diagnostics?.intelligence?.summary;
+  const intelLabel = intelligence?.localAvailable
+    ? STATUS_LABELS.local
+    : intelligence?.cloudAuthenticated
+      ? "Cloud"
+      : "None";
+
+  return {
+    title: "SYSTEM",
+    rows: [
+      { key: "Agents", value: `${agentsDetected}/${agentsTotal}`, kind: agentsDetected > 0 ? "ready" : "warn" },
+      { key: "Runs", value: String(activeRuns), kind: activeRuns > 0 ? "ready" : "muted" },
+      { key: "Intel", value: intelLabel, kind: intelLabel === "None" ? "warn" : "ready" },
+      { key: "Health", value: STATUS_LABELS[healthKind] ?? healthKind, kind: healthKind }
+    ]
+  };
+}
+
+export function buildHomeMissionModel({
+  hasGlobalState = false,
+  diagnostics = null,
+  dashboard = null,
+  layoutMode = LAYOUT_MODES.COMPACT,
+  activityLines = []
+} = {}) {
+  const recommendation = resolveDashboardRecommendation({
+    hasGlobalState,
+    diagnostics,
+    dashboard
+  });
+  const limit = resolveListLimit(layoutMode, { contentRows: 10 });
+  const windowed = windowList(activityLines, limit);
+
+  return {
+    title: "MISSION CONTROL",
+    recommendedTitle: "Recommended action",
+    recommendedAction: recommendation.message,
+    recommendedKind: recommendation.kind,
+    activityTitle: activityLines.length ? "Activity" : "Activity / empty state",
+    activityLines: windowed.items,
+    moreLine: windowed.moreLine,
+    emptyHint: activityLines.length === 0
+      ? "No recent activity. Launch a run when agents are ready."
+      : null
+  };
+}
+
+export function buildFooterModel({
+  view = ORCHESTRATOR_VIEWS.HOME,
+  region = COCKPIT_REGIONS.NAV,
+  helpOpen = false,
+  canCancel = false,
+  unicode = true
+} = {}) {
+  const glyphs = resolveGlyphs(unicode);
+  const parts = [];
+
+  if (helpOpen || view === ORCHESTRATOR_VIEWS.HELP) {
+    parts.push("Esc close help");
+    parts.push("? Help");
+    return { text: parts.join(` ${glyphs.bullet} `) };
+  }
+
+  if (view === ORCHESTRATOR_VIEWS.RUN_DETAIL) {
+    parts.push("R refresh");
+    if (canCancel) parts.push("C cancel");
+    parts.push("Esc Back");
+    return { text: parts.join(` ${glyphs.bullet} `) };
+  }
+
+  parts.push("↑↓ Navigate");
+
+  const showTab = view === ORCHESTRATOR_VIEWS.ACTIVE_RUNS
+    || view === ORCHESTRATOR_VIEWS.RECENT_RUNS
+    || view === ORCHESTRATOR_VIEWS.LAUNCH;
+  if (showTab) {
+    parts.push("Tab Region");
+  }
+
+  if (view === ORCHESTRATOR_VIEWS.HOME
+    || view === ORCHESTRATOR_VIEWS.PROVIDERS
+    || view === ORCHESTRATOR_VIEWS.DIAGNOSTICS
+    || region === COCKPIT_REGIONS.NAV
+    || view === ORCHESTRATOR_VIEWS.ACTIVE_RUNS
+    || view === ORCHESTRATOR_VIEWS.RECENT_RUNS) {
+    parts.push("Enter Open");
+  }
+
+  if (view !== ORCHESTRATOR_VIEWS.LAUNCH) {
+    parts.push("R refresh");
+  }
+
+  parts.push("? Help");
+  parts.push(view === ORCHESTRATOR_VIEWS.HOME ? "Esc Exit" : "Esc Back");
+
+  return { text: parts.join(` ${glyphs.bullet} `) };
+}
+
+export function resolveProjectName(workspaceRoot = "") {
+  if (!workspaceRoot) return "project";
+  const parts = String(workspaceRoot).split(/[/\\]/).filter(Boolean);
+  return parts[parts.length - 1] || "project";
+}

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

@@ -0,0 +1,141 @@
+import React from "react";
+import { Box, Text } from "ink";
+import { COCKPIT_COLORS } from "./theme.js";
+import { CockpitEmptyState } from "./cockpit/primitives.js";
+import {
+  formatDiagnosticsLines,
+  formatLaunchWizardLines,
+  formatProviderLines,
+  formatRunDetailLines,
+  formatRunLines,
+  ORCHESTRATOR_VIEWS,
+  LAUNCH_WIZARD_STEPS
+} from "./orchestrator-state.js";
+
+export function HomeMissionPanel({ model, colorEnabled = true }) {
+  return React.createElement(Box, { flexDirection: "column" },
+    React.createElement(Text, {
+      bold: true,
+      color: colorEnabled ? COCKPIT_COLORS.secondary : undefined
+    }, model.title),
+    React.createElement(Text, { bold: true }, model.recommendedTitle),
+    React.createElement(Text, {
+      color: colorEnabled ? COCKPIT_COLORS.primary : undefined
+    }, model.recommendedAction),
+    React.createElement(Text, null, ""),
+    React.createElement(Text, { bold: true }, model.activityTitle),
+    model.emptyHint
+      ? React.createElement(CockpitEmptyState, {
+        message: model.emptyHint,
+        hint: "Enter on Launch run when ready."
+      })
+      : model.activityLines.map((line) =>
+        React.createElement(Text, { key: line }, line)
+      ),
+    model.moreLine && React.createElement(Text, {
+      color: COCKPIT_COLORS.muted
+    }, model.moreLine)
+  );
+}
+
+export function renderCockpitView({
+  view,
+  dashboard,
+  diagnostics,
+  listIndex,
+  launchStep,
+  launchDraft,
+  launchAgentIndex,
+  launchPermissionIndex,
+  launchableAgents,
+  selectedRun,
+  selectedEvents,
+  homeMission,
+  colorEnabled = true
+}) {
+  switch (view) {
+    case ORCHESTRATOR_VIEWS.HOME:
+      return React.createElement(HomeMissionPanel, { model: homeMission, colorEnabled });
+    case ORCHESTRATOR_VIEWS.ACTIVE_RUNS:
+      return listBlock(
+        "Active runs",
+        formatRunLines(dashboard?.activeRuns ?? [], { emptyMessage: "No active runs." }),
+        listIndex,
+        colorEnabled
+      );
+    case ORCHESTRATOR_VIEWS.RECENT_RUNS:
+      return listBlock(
+        "Recent runs",
+        formatRunLines(dashboard?.recentRuns ?? [], { emptyMessage: "No completed runs yet." }),
+        listIndex,
+        colorEnabled
+      );
+    case ORCHESTRATOR_VIEWS.PROVIDERS:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Providers"),
+        formatProviderLines(dashboard?.providers ?? [])
+          .map((line) => React.createElement(Text, { key: line }, line))
+      );
+    case ORCHESTRATOR_VIEWS.LAUNCH:
+      if (launchableAgents.length === 0) {
+        return React.createElement(CockpitEmptyState, {
+          title: "Launch run",
+          message: "No launchable agents detected.",
+          hint: "Esc to return · check Diagnostics"
+        });
+      }
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Launch run"),
+        formatLaunchWizardLines({
+          step: launchStep,
+          draft: launchDraft,
+          launchableAgents,
+          agentIndex: launchAgentIndex,
+          permissionIndex: launchPermissionIndex
+        }).map((line) => React.createElement(Text, {
+          key: line,
+          color: line.startsWith("›") || line.startsWith(">")
+            ? (colorEnabled ? COCKPIT_COLORS.primary : undefined)
+            : undefined
+        }, line))
+      );
+    case ORCHESTRATOR_VIEWS.RUN_DETAIL:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Run detail"),
+        formatRunDetailLines(selectedRun, selectedEvents)
+          .map((line) => React.createElement(Text, { key: line }, line))
+      );
+    case ORCHESTRATOR_VIEWS.DIAGNOSTICS:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Diagnostics"),
+        formatDiagnosticsLines(diagnostics)
+          .map((line) => React.createElement(Text, { key: line }, line))
+      );
+    case ORCHESTRATOR_VIEWS.HELP:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Help"),
+        React.createElement(Text, null, "Kairo runtime launches and audits agent CLIs you manage."),
+        React.createElement(Text, null, "↑↓ navigate · Tab region · Enter open · Esc back/exit"),
+        React.createElement(Text, null, "R refresh · C cancel active run · ? toggle help"),
+        React.createElement(Text, null, "CLI: kairo run --agent <id> --task \"...\""),
+        React.createElement(Text, null, "Audit trail: ~/.harness/runs/<runId>/")
+      );
+    default: {
+      const _exhaustive = view;
+      return React.createElement(Text, null, `Unknown view: ${_exhaustive}`);
+    }
+  }
+}
+
+function listBlock(title, lines, listIndex, colorEnabled) {
+  return React.createElement(Box, { flexDirection: "column" },
+    React.createElement(Text, { bold: true }, title),
+    lines.map((line, index) => React.createElement(Text, {
+      key: `${index}-${line}`,
+      bold: index === listIndex,
+      color: index === listIndex && colorEnabled ? COCKPIT_COLORS.primary : undefined
+    }, `${index === listIndex ? "› " : "  "}${line}`))
+  );
+}
+
+export { LAUNCH_WIZARD_STEPS };

package/src/global/ink/fullscreen-session.js

@@ -0,0 +1,128 @@
+import ansiEscapes from "ansi-escapes";
+import { stdout as defaultStdout } from "node:process";
+
+const SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+
+/**
+ * Idempotent alternate-screen session for Ink TTY flows.
+ * Enter once for onboarding → setup → dashboard; leave exactly once on any exit.
+ *
+ * @param {{
+ *   stdout?: { isTTY?: boolean, write?: Function },
+ *   ansi?: { enterAlternativeScreen: string, exitAlternativeScreen: string, cursorHide: string, cursorShow: string },
+ *   processRef?: NodeJS.Process,
+ *   enabled?: boolean,
+ *   onSignal?: (signal: string) => void
+ * }} [options]
+ */
+export function createFullscreenSession({
+  stdout = defaultStdout,
+  ansi = ansiEscapes,
+  processRef = process,
+  enabled = Boolean(stdout?.isTTY),
+  onSignal = null
+} = {}) {
+  let active = false;
+  let left = false;
+  const signalHandlers = new Map();
+
+  function write(sequence) {
+    if (!stdout || typeof stdout.write !== "function") return;
+    try {
+      stdout.write(sequence);
+    } catch {
+      // Best-effort restore; never throw from leave path.
+    }
+  }
+
+  function detachSignals() {
+    for (const [signal, handler] of signalHandlers) {
+      try {
+        processRef.removeListener(signal, handler);
+      } catch {
+        // ignore
+      }
+    }
+    signalHandlers.clear();
+  }
+
+  function leave() {
+    if (!active || left) return false;
+    left = true;
+    active = false;
+    detachSignals();
+    write(ansi.cursorShow);
+    write(ansi.exitAlternativeScreen);
+    return true;
+  }
+
+  function defaultSignalExit(signal) {
+    const code = signal === "SIGINT" ? 130 : signal === "SIGTERM" ? 143 : 129;
+    try {
+      processRef.exit(code);
+    } catch {
+      // ignore in constrained environments
+    }
+  }
+
+  function attachSignals() {
+    for (const signal of SIGNALS) {
+      const handler = () => {
+        leave();
+        if (typeof onSignal === "function") {
+          onSignal(signal);
+          return;
+        }
+        defaultSignalExit(signal);
+      };
+      signalHandlers.set(signal, handler);
+      processRef.on(signal, handler);
+    }
+  }
+
+  function enter() {
+    if (!enabled) return false;
+    if (active) return false;
+    left = false;
+    active = true;
+    write(ansi.enterAlternativeScreen);
+    write(ansi.cursorHide);
+    attachSignals();
+    return true;
+  }
+
+  function isActive() {
+    return active && !left;
+  }
+
+  return {
+    enter,
+    leave,
+    isActive,
+    get enabled() {
+      return enabled;
+    }
+  };
+}
+
+/**
+ * Run an async body inside a fullscreen session (enter → finally leave).
+ * If `sessionOrOptions` is an existing session that is already active, does not leave it.
+ */
+export async function withFullscreenSession(sessionOrOptions, body) {
+  const isExisting = typeof sessionOrOptions?.enter === "function";
+  const session = isExisting
+    ? sessionOrOptions
+    : createFullscreenSession(sessionOrOptions);
+
+  const wasActive = session.isActive();
+  const didEnter = wasActive ? false : session.enter();
+
+  try {
+    return await body(session);
+  } finally {
+    if (didEnter) {
+      session.leave();
+    }
+  }
+}

package/src/global/ink/launch-input.js

@@ -0,0 +1,109 @@
+import {
+  LAUNCH_PERMISSION_OPTIONS,
+  LAUNCH_WIZARD_STEPS,
+  retreatLaunchWizardStep
+} from "./orchestrator-state.js";
+
+/**
+ * Launch-wizard key handler.
+ * Returns true when consumed, "retreated" when Esc stepped back, false otherwise.
+ */
+export function handleLaunchInput(ctx) {
+  const {
+    key,
+    inputKey,
+    launchStep,
+    launchDraft,
+    launchableAgents,
+    launchAgentIndex,
+    launchPermissionIndex,
+    setLaunchAgentIndex,
+    setLaunchDraft,
+    setLaunchStep,
+    setLaunchPermissionIndex,
+    setError,
+    handleLaunch,
+    reload,
+    allowEscapeRetreat = false
+  } = ctx;
+
+  if (allowEscapeRetreat && key.escape) {
+    if (launchStep === LAUNCH_WIZARD_STEPS.AGENT) {
+      return false;
+    }
+    setLaunchStep(retreatLaunchWizardStep(launchStep));
+    return "retreated";
+  }
+
+  if (launchStep === LAUNCH_WIZARD_STEPS.AGENT) {
+    if (key.upArrow) {
+      setLaunchAgentIndex((index) => Math.max(0, index - 1));
+      return true;
+    }
+    if (key.downArrow) {
+      setLaunchAgentIndex((index) => Math.min(launchableAgents.length - 1, index + 1));
+      return true;
+    }
+    if (key.return) {
+      const agentId = launchableAgents[launchAgentIndex];
+      setLaunchDraft((draft) => ({ ...draft, agentId }));
+      setLaunchStep(LAUNCH_WIZARD_STEPS.TASK);
+      return true;
+    }
+    return true;
+  }
+
+  if (launchStep === LAUNCH_WIZARD_STEPS.TASK || launchStep === LAUNCH_WIZARD_STEPS.MODEL) {
+    const field = launchStep === LAUNCH_WIZARD_STEPS.TASK ? "task" : "model";
+    if (key.return) {
+      if (field === "task" && !launchDraft.task.trim()) {
+        setError("Task cannot be empty.");
+        return true;
+      }
+      setLaunchStep(field === "task" ? LAUNCH_WIZARD_STEPS.MODEL : LAUNCH_WIZARD_STEPS.PERMISSIONS);
+      return true;
+    }
+    if (key.backspace || key.delete) {
+      setLaunchDraft((draft) => ({ ...draft, [field]: draft[field].slice(0, -1) }));
+      return true;
+    }
+    if (inputKey && inputKey.length === 1 && !key.ctrl && !key.meta) {
+      setLaunchDraft((draft) => ({ ...draft, [field]: `${draft[field]}${inputKey}` }));
+      return true;
+    }
+    return true;
+  }
+
+  if (launchStep === LAUNCH_WIZARD_STEPS.PERMISSIONS) {
+    if (key.upArrow) {
+      setLaunchPermissionIndex((index) => Math.max(0, index - 1));
+      return true;
+    }
+    if (key.downArrow) {
+      setLaunchPermissionIndex((index) => Math.min(LAUNCH_PERMISSION_OPTIONS.length - 1, index + 1));
+      return true;
+    }
+    if (key.return) {
+      setLaunchStep(LAUNCH_WIZARD_STEPS.CONFIRM);
+      return true;
+    }
+    return true;
+  }
+
+  if (launchStep === LAUNCH_WIZARD_STEPS.CONFIRM) {
+    if (key.return) {
+      handleLaunch({ ...launchDraft, permissionIndex: launchPermissionIndex });
+      return true;
+    }
+    if (key.escape) {
+      setLaunchStep(retreatLaunchWizardStep(launchStep));
+      return allowEscapeRetreat ? "retreated" : true;
+    }
+  }
+
+  if (inputKey.toLowerCase() === "r") {
+    reload().catch(() => {});
+    return true;
+  }
+  return false;
+}

package/src/global/ink/layout.js

@@ -0,0 +1,34 @@
+import { LAYOUT_MODES } from "./terminal-capabilities.js";
+
+/**
+ * Pure layout mode from terminal size.
+ * @returns {"wide"|"compact"|"minimal"|null} null when below Ink gate (<60 cols)
+ */
+export function resolveLayoutMode({ columns = 80, rows = 24 } = {}) {
+  const cols = Number.isFinite(columns) && columns > 0 ? columns : 0;
+  const r = Number.isFinite(rows) && rows > 0 ? rows : 0;
+
+  if (cols < 60) return null;
+
+  if (cols >= 100 && r >= 28) return LAYOUT_MODES.WIDE;
+  if (cols >= 72 && r >= 20) return LAYOUT_MODES.COMPACT;
+  return LAYOUT_MODES.MINIMAL;
+}
+
+/**
+ * Suggested visible list limit for the active layout.
+ */
+export function resolveListLimit(layoutMode, { contentRows = 12 } = {}) {
+  switch (layoutMode) {
+    case LAYOUT_MODES.WIDE:
+      return Math.max(6, Math.min(16, contentRows - 4));
+    case LAYOUT_MODES.COMPACT:
+      return Math.max(4, Math.min(10, contentRows - 4));
+    case LAYOUT_MODES.MINIMAL:
+      return Math.max(3, Math.min(6, contentRows - 2));
+    default:
+      return 4;
+  }
+}
+
+export { LAYOUT_MODES };

package/src/global/ink/list-window.js

@@ -0,0 +1,38 @@
+/**
+ * Truncate a list for a fixed viewport with an overflow indicator.
+ *
+ * @template T
+ * @param {T[]} items
+ * @param {number} limit
+ * @param {{ moreLabel?: string }} [options]
+ * @returns {{ items: T[], hiddenCount: number, hasMore: boolean, moreLine: string | null }}
+ */
+export function windowList(items = [], limit = 8, { moreLabel = "… more" } = {}) {
+  const safeLimit = Math.max(0, Number(limit) || 0);
+  if (safeLimit === 0) {
+    return {
+      items: [],
+      hiddenCount: items.length,
+      hasMore: items.length > 0,
+      moreLine: items.length > 0 ? `${moreLabel} (${items.length})` : null
+    };
+  }
+
+  if (items.length <= safeLimit) {
+    return {
+      items: [...items],
+      hiddenCount: 0,
+      hasMore: false,
+      moreLine: null
+    };
+  }
+
+  const visible = items.slice(0, safeLimit);
+  const hiddenCount = items.length - safeLimit;
+  return {
+    items: visible,
+    hiddenCount,
+    hasMore: true,
+    moreLine: `${moreLabel} (${hiddenCount})`
+  };
+}