@kal-elsam/kairo-runtime 0.2.1 → 0.2.3

package/README.md

@@ -24,13 +24,24 @@ 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 → operations dashboard.
+
+**Later runs** (state present): operations dashboard with a stable purpose line and a
+contextual next step (configure, enable intelligence, launch a run, or review problems).
+
+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.1",
+  "version": "0.2.3",
   "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",

package/scripts/runtime-mvp-smoke.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+KAIRO=(node "$ROOT/bin/kairo.js")
+WORKSPACE="${SMOKE_WORKSPACE:-$ROOT}"
+HOME_DIR="${HARNESS_HOME:-$(mktemp -d /tmp/kairo-runtime-smoke-XXXXXX)}"
+export HARNESS_HOME="$HOME_DIR"
+export HARNESS_INK=0
+
+PROMPT_A="List the files in the current directory and summarize in one sentence."
+PROMPT_B="Reply with exactly the single word OK and nothing else."
+PROMPT_SECRET="SMOKE_SECRET_PROMPT_$(date +%s)_do_not_persist"
+SMOKE_MODEL="${SMOKE_MODEL:-}"
+
+MODEL_ARGS=()
+if [[ -n "$SMOKE_MODEL" ]]; then
+  MODEL_ARGS=(--model "$SMOKE_MODEL")
+fi
+
+log() { printf '[smoke] %s\n' "$*"; }
+
+assert_no_prompt() {
+  local dir=$1 prompt=$2
+  if grep -qF "$prompt" "$dir/state.json" 2>/dev/null; then
+    echo "FAIL: prompt found in state.json for $dir" >&2
+    return 1
+  fi
+  if grep -qF "$prompt" "$dir/events.jsonl" 2>/dev/null; then
+    echo "FAIL: prompt found in events.jsonl for $dir" >&2
+    return 1
+  fi
+  if [[ -f "$dir/handoff.json" ]]; then
+    echo "FAIL: handoff.json still present for $dir" >&2
+    return 1
+  fi
+}
+
+log "HARNESS_HOME=$HOME_DIR"
+log "WORKSPACE=$WORKSPACE"
+if [[ -n "$SMOKE_MODEL" ]]; then
+  log "SMOKE_MODEL=$SMOKE_MODEL"
+else
+  log "SMOKE_MODEL=(not set — Case 2 may fail if Codex default model is incompatible)"
+fi
+
+# --- Case 1: detached run + cross-process list/show/stop ---
+log "=== Case 1: --no-wait + cross-process supervision ==="
+START_A=$(python3 -c 'import time; print(int(time.time()*1000))')
+OUT_A=$("${KAIRO[@]}" run --agent codex --task "$PROMPT_A" --cwd "$WORKSPACE" "${MODEL_ARGS[@]}" --no-wait 2>&1)
+END_A=$(python3 -c 'import time; print(int(time.time()*1000))')
+DUR_A=$((END_A - START_A))
+
+RUN_ID=$(printf '%s\n' "$OUT_A" | sed -n 's/.*\(run_[a-z0-9_]*\).*/\1/p' | head -1)
+if [[ -z "$RUN_ID" ]]; then
+  echo "FAIL: could not parse runId from output:" >&2
+  echo "$OUT_A" >&2
+  exit 1
+fi
+
+log "Case 1 runId=$RUN_ID parent_return_ms=$DUR_A"
+if (( DUR_A > 5000 )); then
+  echo "FAIL: --no-wait took ${DUR_A}ms (>5000ms)" >&2
+  exit 1
+fi
+
+sleep 1
+LIST_B=$("${KAIRO[@]}" runs list --cwd "$WORKSPACE" 2>&1)
+if printf '%s\n' "$LIST_B" | grep -q interrupted; then
+  echo "FAIL: runs list shows interrupted" >&2
+  echo "$LIST_B" >&2
+  exit 1
+fi
+if ! printf '%s\n' "$LIST_B" | grep -q "$RUN_ID"; then
+  echo "FAIL: run not listed" >&2
+  echo "$LIST_B" >&2
+  exit 1
+fi
+if ! printf '%s\n' "$LIST_B" | grep -Eq "running|starting"; then
+  echo "FAIL: run not active in list" >&2
+  echo "$LIST_B" >&2
+  exit 1
+fi
+
+SHOW_B=$("${KAIRO[@]}" runs show "$RUN_ID" --cwd "$WORKSPACE" 2>&1)
+if printf '%s\n' "$SHOW_B" | grep -q interrupted; then
+  echo "FAIL: runs show reports interrupted" >&2
+  echo "$SHOW_B" >&2
+  exit 1
+fi
+
+START_STOP=$(python3 -c 'import time; print(int(time.time()*1000))')
+STOP_B=$("${KAIRO[@]}" runs stop "$RUN_ID" --cwd "$WORKSPACE" 2>&1)
+END_STOP=$(python3 -c 'import time; print(int(time.time()*1000))')
+DUR_STOP=$((END_STOP - START_STOP))
+
+sleep 1
+FINAL_A=$("${KAIRO[@]}" runs show "$RUN_ID" --json --cwd "$WORKSPACE")
+STATE_A=$(printf '%s\n' "$FINAL_A" | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{const j=JSON.parse(s);console.log(j.metadata.state)})')
+if [[ "$STATE_A" != "cancelled" ]]; then
+  echo "FAIL: expected cancelled, got $STATE_A" >&2
+  exit 1
+fi
+
+RUN_DIR_A="$HOME_DIR/.harness/runs/$RUN_ID"
+assert_no_prompt "$RUN_DIR_A" "$PROMPT_A"
+log "Case 1 PASS state=$STATE_A stop_ms=$DUR_STOP"
+
+# --- Case 2: normal completion (must be completed) ---
+log "=== Case 2: wait for normal completion ==="
+START_B=$(python3 -c 'import time; print(int(time.time()*1000))')
+OUT_B=$("${KAIRO[@]}" run --agent codex --task "$PROMPT_B" --cwd "$WORKSPACE" --permissions yolo "${MODEL_ARGS[@]}" 2>&1)
+END_B=$(python3 -c 'import time; print(int(time.time()*1000))')
+DUR_B=$((END_B - START_B))
+
+RUN_ID_B=$(printf '%s\n' "$OUT_B" | sed -n 's/.*\(run_[a-z0-9_]*\).*/\1/p' | head -1)
+FINAL_B=$("${KAIRO[@]}" runs show "$RUN_ID_B" --json --cwd "$WORKSPACE")
+STATE_B=$(printf '%s\n' "$FINAL_B" | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>{const j=JSON.parse(s);console.log(j.metadata.state)})')
+
+if [[ "$STATE_B" != "completed" ]]; then
+  echo "FAIL: expected completed, got $STATE_B" >&2
+  echo "$OUT_B" >&2
+  if [[ -z "$SMOKE_MODEL" ]]; then
+    echo "Hint: set SMOKE_MODEL to a Codex model compatible with your account/CLI version." >&2
+  fi
+  exit 1
+fi
+
+RUN_DIR_B="$HOME_DIR/.harness/runs/$RUN_ID_B"
+assert_no_prompt "$RUN_DIR_B" "$PROMPT_B"
+log "Case 2 PASS runId=$RUN_ID_B state=$STATE_B duration_ms=$DUR_B"
+
+# --- Case 3: privacy spot-check with unique secret prompt ---
+log "=== Case 3: privacy secret prompt ==="
+START_C=$(python3 -c 'import time; print(int(time.time()*1000))')
+OUT_C=$("${KAIRO[@]}" run --agent codex --task "$PROMPT_SECRET" --cwd "$WORKSPACE" --permissions yolo "${MODEL_ARGS[@]}" --no-wait 2>&1)
+RUN_ID_C=$(printf '%s\n' "$OUT_C" | sed -n 's/.*\(run_[a-z0-9_]*\).*/\1/p' | head -1)
+sleep 2
+"${KAIRO[@]}" runs stop "$RUN_ID_C" --cwd "$WORKSPACE" >/dev/null 2>&1 || true
+sleep 1
+RUN_DIR_C="$HOME_DIR/.harness/runs/$RUN_ID_C"
+assert_no_prompt "$RUN_DIR_C" "$PROMPT_SECRET"
+END_C=$(python3 -c 'import time; print(int(time.time()*1000))')
+DUR_C=$((END_C - START_C))
+log "Case 3 PASS runId=$RUN_ID_C duration_ms=$DUR_C"
+
+printf '\n=== SMOKE SUMMARY ===\n'
+printf 'Case 1 (detach+stop): runId=%s state=%s parent_ms=%s stop_ms=%s\n' "$RUN_ID" "$STATE_A" "$DUR_A" "$DUR_STOP"
+printf 'Case 2 (complete):    runId=%s state=%s duration_ms=%s model=%s\n' "$RUN_ID_B" "$STATE_B" "$DUR_B" "${SMOKE_MODEL:-default}"
+printf 'Case 3 (privacy):     runId=%s duration_ms=%s\n' "$RUN_ID_C" "$DUR_C"
+printf 'HARNESS_HOME=%s\n' "$HOME_DIR"
+printf 'ALL PASS\n'

package/src/cli.js

@@ -32,6 +32,7 @@ import { resolveHomeDir } from "./global/paths.js";
 import { runWorkspaceDetect, runWorkspaceDoctor, runWorkspaceInit, runWorkspaceUpdate } from "./workspace-cli.js";
 import { runOrchestratorDiagnostics, runOrchestratorShell } from "./global/orchestrator.js";
 import { runIntelligenceCli } from "./global/intelligence-cli.js";
+import { runGlobalRun, runGlobalRuns } from "./global/runtime/run-cli.js";
 import {
   LEGACY_PACKAGE_NAME,
   PACKAGE_NAME,
@@ -41,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 };
 
@@ -49,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") {
@@ -68,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(),
@@ -86,6 +100,12 @@ export async function runCli(argv) {
         json: optionsWithPolicy.json
       });
       return;
+    case "run":
+      await runGlobalRun(optionsWithPolicy, packageManifest);
+      return;
+    case "runs":
+      await runGlobalRuns(optionsWithPolicy, packageManifest);
+      return;
     case "intelligence":
       await runIntelligenceCli(optionsWithPolicy, packageManifest);
       return;
@@ -333,6 +353,17 @@ export function parseArgs(argv) {
     intelligenceTask: null,
     intelligencePrompt: null,
     intelligencePaths: [],
+    runsAction: null,
+    runId: null,
+    agent: null,
+    task: null,
+    model: null,
+    permissions: null,
+    captureTranscript: false,
+    follow: false,
+    wait: true,
+    activeOnly: false,
+    timeoutMs: null,
     includePrivate: false,
     cloudConsent: false
   };
@@ -349,6 +380,10 @@ export function parseArgs(argv) {
     parseHistoryAction(args, options);
   }
 
+  if (command === "runs") {
+    parseRunsAction(args, options);
+  }
+
   if (command === "intelligence") {
     parseIntelligenceAction(args, options);
   }
@@ -414,12 +449,27 @@ export function parseArgs(argv) {
     else if (arg === "--out") options.outPath = resolve(args[++index]);
     else if (arg.startsWith("--out=")) options.outPath = resolve(arg.slice("--out=".length));
     else if (arg === "--simple") options.simple = true;
-    else if (arg === "--task") options.intelligenceTask = args[++index];
-    else if (arg.startsWith("--task=")) options.intelligenceTask = arg.slice("--task=".length);
+    else if (arg === "--task" || arg.startsWith("--task=")) {
+      const taskValue = arg.startsWith("--task=") ? arg.slice("--task=".length) : args[++index];
+      if (command === "run") options.task = taskValue;
+      else options.intelligenceTask = taskValue;
+    }
     else if (arg === "--prompt") options.intelligencePrompt = args[++index];
     else if (arg.startsWith("--prompt=")) options.intelligencePrompt = arg.slice("--prompt=".length);
     else if (arg === "--paths") options.intelligencePaths = parsePathList(args[++index]);
     else if (arg.startsWith("--paths=")) options.intelligencePaths = parsePathList(arg.slice("--paths=".length));
+    else if (arg === "--agent") options.agent = args[++index];
+    else if (arg.startsWith("--agent=")) options.agent = arg.slice("--agent=".length);
+    else if (arg === "--model") options.model = args[++index];
+    else if (arg.startsWith("--model=")) options.model = arg.slice("--model=".length);
+    else if (arg === "--permissions") options.permissions = parsePathList(args[++index]);
+    else if (arg.startsWith("--permissions=")) options.permissions = parsePathList(arg.slice("--permissions=".length));
+    else if (arg === "--capture-transcript") options.captureTranscript = true;
+    else if (arg === "--follow") options.follow = true;
+    else if (arg === "--no-wait") options.wait = false;
+    else if (arg === "--active-only") options.activeOnly = true;
+    else if (arg === "--timeout") options.timeoutMs = parsePositiveInt(args[++index], "timeout") * 1000;
+    else if (arg.startsWith("--timeout=")) options.timeoutMs = parsePositiveInt(arg.slice("--timeout=".length), "timeout") * 1000;
     else if (arg === "--include-private") options.includePrivate = true;
     else if (arg === "--cloud-consent") options.cloudConsent = true;
     else if (arg === "--help" || arg === "-h") options.help = true;
@@ -427,7 +477,11 @@ export function parseArgs(argv) {
     else throw new Error(`Unknown option "${arg}".`);
   }
 
-  return { command, options };
+  if (command === "run" && !options.task && args.length > 0) {
+    options.task = args.join(" ").trim();
+  }
+
+  return { command, options, isImplicitCommand: implicitCommand };
 }
 
 function parseComponentsAction(args, options) {
@@ -512,6 +566,30 @@ function parseHistoryAction(args, options) {
   throw new Error(`Unknown history action "${action}". Use last or omit for the full log.`);
 }
 
+function parseRunsAction(args, options) {
+  const action = args[0];
+
+  if (!action || action.startsWith("-")) {
+    options.runsAction = "list";
+    return;
+  }
+
+  if (!new Set(["list", "show", "stop"]).has(action)) {
+    throw new Error(`Unknown runs action "${action}". Use list, show, or stop.`);
+  }
+
+  args.shift();
+  options.runsAction = action;
+
+  if (action === "show" || action === "stop") {
+    const runId = args[0];
+    if (!runId || runId.startsWith("-")) {
+      throw new Error(`Missing run id. Use: ${formatCliCommand(`runs ${action} <runId>`)}`);
+    }
+    options.runId = args.shift();
+  }
+}
+
 function parseIntelligenceAction(args, options) {
   const action = args[0];
   if (!action || action.startsWith("-")) {
@@ -559,6 +637,8 @@ function normalizeCommand(command) {
   if (command === "install" || command === "i") return "install";
   if (command === "shell") return "shell";
   if (command === "orchestrator") return "orchestrator";
+  if (command === "run") return "run";
+  if (command === "runs") return "runs";
   if (command === "intelligence" || command === "intel") return "intelligence";
   if (command === "setup") return "setup";
   if (command === "status") return "status";
@@ -616,10 +696,15 @@ 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 → dashboard (TTY).
+                                      Later: operations dashboard with next-step guidance.
   ${cli} --dry-run                      Setup dry-run (scriptable)
   ${cli} --version
-  ${cli} shell                          Interactive orchestrator shell (TTY)
+  ${cli} shell                          Operations dashboard (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]
+  ${cli} runs stop <runId> [--json]
   ${cli} orchestrator [--json]          Read-only agent capability diagnostics
   ${cli} intelligence [status|models|context|route|ask] [--json]
   ${cli} intelligence ask --prompt "..." [--cloud-consent] [--yes] [--paths a,b]
@@ -656,7 +741,10 @@ Scopes:
                           Explicit --scope=workspace only.
 
 Commands:
-  shell      Interactive Ink orchestrator (TTY). Bare ${cli} opens this in TTY sessions.
+  shell      Operations dashboard (TTY). Bare ${cli} opens onboarding when ~/.harness/state.json
+             is missing, otherwise the dashboard. Explicit ${cli} shell always opens the dashboard.
+  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).
   intelligence  Harness Engineering layer: backends, context packs, routing, budgets.
              Local-first (Ollama). Cloud (OpenRouter/free) only with --cloud-consent.

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