@kal-elsam/kairo-runtime 0.1.4 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "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/src/cli.js

@@ -30,6 +30,7 @@ import {
 import { applyPolicyToOptions, loadPolicyFile } from "./global/policy.js";
 import { resolveHomeDir } from "./global/paths.js";
 import { runWorkspaceDetect, runWorkspaceDoctor, runWorkspaceInit, runWorkspaceUpdate } from "./workspace-cli.js";
+import { runOrchestratorDiagnostics, runOrchestratorShell } from "./global/orchestrator.js";
 import {
   LEGACY_PACKAGE_NAME,
   PACKAGE_NAME,
@@ -66,6 +67,24 @@ export async function runCli(argv) {
   const invoke = resolveSuggestedInvocation(packageManifest.name);
 
   switch (command) {
+    case "shell":
+      await runOrchestratorShell({
+        packageRoot,
+        packageManifest,
+        workspaceRoot: optionsWithPolicy.cwd,
+        interactive: optionsWithPolicy.interactive
+      });
+      return;
+    case "orchestrator":
+      await runOrchestratorDiagnostics({
+        homeDir: resolveHomeDir(),
+        workspaceRoot: optionsWithPolicy.cwd,
+        packageName: packageManifest.name,
+        packageRoot,
+        cliVersion: packageManifest.version,
+        json: optionsWithPolicy.json
+      });
+      return;
     case "setup":
       await runGlobalSetup(optionsWithPolicy, packageManifest, packageRoot);
       return;
@@ -219,7 +238,37 @@ function resolveImplicitCommand(args) {
   if (argsWantsWorkspaceScope(args)) {
     return "init";
   }
-  return "setup";
+  if (hasImplicitSetupFlags(args)) {
+    return "setup";
+  }
+  return "shell";
+}
+
+function hasImplicitSetupFlags(args) {
+  const setupFlags = new Set([
+    "--dry-run",
+    "--yes",
+    "-y",
+    "--confirm",
+    "--simple",
+    "--no-preflight",
+    "--all-adapters",
+    "--no-default-components",
+    "--detect"
+  ]);
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (setupFlags.has(arg)) return true;
+    if (arg.startsWith("--mode=")) return true;
+    if (arg.startsWith("--adapters=") || arg.startsWith("--agents=")) return true;
+    if (arg.startsWith("--components=")) return true;
+    if (arg === "--mode" || arg === "--adapters" || arg === "--agents" || arg === "--components") {
+      return true;
+    }
+  }
+
+  return false;
 }
 
 function argsWantsWorkspaceScope(args) {
@@ -461,6 +510,8 @@ function normalizeCommand(command) {
   if (!command) return "install";
 
   if (command === "install" || command === "i") return "install";
+  if (command === "shell") return "shell";
+  if (command === "orchestrator") return "orchestrator";
   if (command === "setup") return "setup";
   if (command === "status") return "status";
   if (command === "sync") return "sync";
@@ -517,8 +568,11 @@ sections, components, backups, and drift repair under ~/.harness.
 Bootstrap: see README.md (curl install.sh or npx ${PACKAGE_NAME}).
 
 Usage:
-  ${cli} [--dry-run] [--yes] [--confirm] [--agents <list|all>] [--components <list>]
+  ${cli}                              Interactive orchestrator shell (TTY)
+  ${cli} --dry-run                      Setup dry-run (scriptable)
   ${cli} --version
+  ${cli} shell                          Interactive orchestrator shell (TTY)
+  ${cli} orchestrator [--json]          Read-only agent capability diagnostics
   ${cli} setup [--dry-run] [--yes] [--confirm] [--simple] [--no-preflight] [--agents <list|all>] [--components <list>]
   ${cli} status [--json]
   ${cli} sync [--dry-run] [--yes] [--confirm] [--json] [--no-preflight]
@@ -552,7 +606,9 @@ Scopes:
                           Explicit --scope=workspace only.
 
 Commands:
-  setup      Interactive Ink UI (TTY). Use --simple for Clack prompts.
+  shell      Interactive Ink orchestrator (TTY). Bare ${cli} opens this in TTY sessions.
+  orchestrator  Read-only capability registry diagnostics (--json supported).
+  setup      Managed ecosystem setup. Interactive Ink UI (TTY). Use --simple for Clack prompts.
   status     Control panel: agents, components, drift, backups, next action.
   sync       Converge managed content (repair drift), then show status.
   upgrade    Preview or apply ecosystem updates (apply requires --yes).

package/src/global/action-planner.js

@@ -0,0 +1,178 @@
+import { CAPABILITY_STATES } from "./capability-states.js";
+import { inspectAllCapabilities } from "./capability-registry.js";
+import { resolveProfile, resolveProfileAgents } from "./profile.js";
+import { formatCliCommand } from "./brand/cli.js";
+
+export const PLAN_ACTIONS = {
+  DIAGNOSE: "diagnose",
+  SETUP: "setup",
+  SYNC: "sync",
+  INSTALL: "install",
+  STATUS: "status"
+};
+
+export async function buildReadOnlyDiagnostics({
+  homeDir,
+  workspaceRoot,
+  packageName,
+  packageRoot,
+  cliVersion
+}) {
+  const [{ profile, sources }, capabilities] = await Promise.all([
+    resolveProfile({ homeDir, workspaceRoot }),
+    inspectAllCapabilities({ homeDir, workspaceRoot, packageName })
+  ]);
+
+  const detectedIds = capabilities.filter((entry) => entry.detected).map((entry) => entry.id);
+  const profileAgents = resolveProfileAgents(profile, detectedIds);
+  const diagnostics = summarizeDiagnostics(capabilities);
+
+  return {
+    readOnly: true,
+    cliVersion,
+    profile: { ...profile, sources },
+    capabilities,
+    profileAgents,
+    diagnostics,
+    recommendations: buildDiagnosticRecommendations({ capabilities, profile, diagnostics })
+  };
+}
+
+export async function buildActionPlan({
+  action,
+  homeDir,
+  workspaceRoot,
+  packageName,
+  options = {}
+}) {
+  const diagnostics = await buildReadOnlyDiagnostics({
+    homeDir,
+    workspaceRoot,
+    packageName,
+    packageRoot: options.packageRoot ?? null,
+    cliVersion: options.cliVersion ?? null
+  });
+
+  const steps = [];
+  const warnings = [];
+
+  switch (action) {
+    case PLAN_ACTIONS.DIAGNOSE:
+    case PLAN_ACTIONS.STATUS:
+      return {
+        action,
+        readOnly: true,
+        requiresConfirmation: false,
+        steps: ["Show ecosystem diagnostics (read-only)."],
+        diagnostics,
+        warnings
+      };
+    case PLAN_ACTIONS.SETUP:
+    case PLAN_ACTIONS.INSTALL:
+      steps.push(`Target agents: ${diagnostics.profileAgents.join(", ")}`);
+      steps.push("Preview managed section changes under ~/.harness and agent config files.");
+      steps.push("Create backups before writing managed content.");
+      if (options.dryRun) {
+        steps.push("Dry run: no files will be written.");
+      }
+      return {
+        action,
+        readOnly: Boolean(options.dryRun),
+        requiresConfirmation: !options.dryRun,
+        steps,
+        diagnostics,
+        warnings: collectCapabilityWarnings(diagnostics.capabilities)
+      };
+    case PLAN_ACTIONS.SYNC:
+      steps.push("Compare managed content against bundled assets.");
+      steps.push("Repair drift in agent config files when differences are found.");
+      if (options.dryRun) {
+        steps.push("Dry run: show planned repairs only.");
+      }
+      return {
+        action,
+        readOnly: Boolean(options.dryRun),
+        requiresConfirmation: !options.dryRun,
+        steps,
+        diagnostics,
+        warnings: collectCapabilityWarnings(diagnostics.capabilities)
+      };
+    default: {
+      const _exhaustive = action;
+      throw new Error(`Unknown plan action "${_exhaustive}".`);
+    }
+  }
+}
+
+export function shouldExecutePlan(plan, { confirmed = false } = {}) {
+  if (plan.readOnly) return true;
+  return confirmed;
+}
+
+export function formatActionPlan(plan) {
+  const lines = [];
+  lines.push(`Action: ${plan.action}`);
+  lines.push(`Mode: ${plan.readOnly ? "read-only" : "write"}`);
+  lines.push(`Confirmation required: ${plan.requiresConfirmation ? "yes" : "no"}`);
+  lines.push("");
+  lines.push("Steps:");
+  for (const step of plan.steps) {
+    lines.push(`  - ${step}`);
+  }
+
+  if (plan.warnings.length > 0) {
+    lines.push("");
+    lines.push("Warnings:");
+    for (const warning of plan.warnings) {
+      lines.push(`  - ${warning}`);
+    }
+  }
+
+  if (plan.diagnostics.recommendations.length > 0) {
+    lines.push("");
+    lines.push("Recommendations:");
+    for (const recommendation of plan.diagnostics.recommendations) {
+      lines.push(`  - ${recommendation}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function summarizeDiagnostics(capabilities) {
+  return {
+    detected: capabilities.filter((entry) => entry.detected).length,
+    available: capabilities.filter((entry) => entry.state === CAPABILITY_STATES.AVAILABLE).length,
+    unknown: capabilities.filter((entry) => entry.state === CAPABILITY_STATES.UNKNOWN).length,
+    errors: capabilities.filter((entry) => entry.state === CAPABILITY_STATES.ERROR).length
+  };
+}
+
+function buildDiagnosticRecommendations({ capabilities, profile, diagnostics }) {
+  const recommendations = [];
+
+  if (diagnostics.detected === 0) {
+    recommendations.push(`No agents detected. Run ${formatCliCommand("detect")} or install a supported agent CLI.`);
+  }
+
+  if (profile.coordinator) {
+    const coordinator = capabilities.find((entry) => entry.id === profile.coordinator);
+    if (!coordinator?.detected && coordinator?.state === CAPABILITY_STATES.UNKNOWN) {
+      recommendations.push(`Profile coordinator "${profile.coordinator}" is not detected on this machine.`);
+    }
+  }
+
+  for (const capability of capabilities) {
+    if (capability.recommendation) {
+      recommendations.push(`${capability.label}: ${capability.recommendation}`);
+    }
+  }
+
+  return [...new Set(recommendations)];
+}
+
+function collectCapabilityWarnings(capabilities) {
+  return capabilities
+    .filter((entry) => entry.state === CAPABILITY_STATES.ERROR || entry.state === CAPABILITY_STATES.UNKNOWN)
+    .map((entry) => `${entry.label} is ${entry.state}${entry.error ? ` (${entry.error})` : ""}.`);
+}

package/src/global/agent-capabilities/create-capability-adapter.js

@@ -0,0 +1,224 @@
+import { CAPABILITY_STATES } from "../capability-states.js";
+import {
+  isExecutableAvailable,
+  parseVersionFromOutput,
+  probeCommand,
+  resolveProbeState
+} from "../cli-probe.js";
+
+export function createAgentCapabilityAdapter({
+  id,
+  label,
+  managedAdapter,
+  executable = null,
+  versionArgs = ["--version"],
+  authArgs = null,
+  modelsArgs = null,
+  opaqueAuth = false,
+  runExecutable = null
+}) {
+  const cliName = runExecutable ?? executable;
+
+  return {
+    id,
+    label,
+    managedAdapter,
+
+    detect(context) {
+      return managedAdapter.detect(context);
+    },
+
+    inspect(context, { probeImpl = defaultProbe } = {}) {
+      const detected = managedAdapter.detect(context);
+      const cliAvailable = executable ? isExecutableAvailable(executable) : false;
+
+      if (!detected && !cliAvailable) {
+        return buildInspection({
+          id,
+          label,
+          state: CAPABILITY_STATES.UNKNOWN,
+          detected: false,
+          cliAvailable: false,
+          version: null,
+          authenticated: null,
+          recommendation: `Install ${label} or run ${formatCliCommand("setup")} to configure managed sections.`
+        });
+      }
+
+      if (opaqueAuth) {
+        return buildInspection({
+          id,
+          label,
+          state: detected || cliAvailable ? CAPABILITY_STATES.DETECTED : CAPABILITY_STATES.UNKNOWN,
+          detected,
+          cliAvailable,
+          version: null,
+          authenticated: null,
+          recommendation: detected
+            ? `${label} config detected. Authentication status is provider-managed.`
+            : `Install ${label} to enable managed configuration.`
+        });
+      }
+
+      return probeImpl({
+        id,
+        label,
+        detected,
+        cliAvailable,
+        executable,
+        versionArgs,
+        authArgs
+      });
+    },
+
+    listModels(context, { probeImpl = defaultProbeModels } = {}) {
+      if (!modelsArgs || !executable) return null;
+      if (!isExecutableAvailable(executable)) return null;
+      return probeImpl({ executable, modelsArgs, context });
+    },
+
+    run(context, { args = [], cwd = context.workspaceRoot ?? process.cwd(), spawnImpl = probeCommand } = {}) {
+      if (!cliName) {
+        return {
+          ok: false,
+          state: CAPABILITY_STATES.ERROR,
+          message: `${label} does not expose a delegatable CLI through Kairo.`
+        };
+      }
+
+      if (!isExecutableAvailable(cliName)) {
+        return {
+          ok: false,
+          state: CAPABILITY_STATES.ERROR,
+          message: `${label} CLI "${cliName}" is not on PATH. Install the agent or add it to PATH.`
+        };
+      }
+
+      const result = spawnImpl(cliName, args, { cwd, env: process.env });
+
+      if (!result.ok) {
+        const detail = result.stderr || result.stdout || result.error || "unknown error";
+        return {
+          ok: false,
+          state: CAPABILITY_STATES.ERROR,
+          message: `${label} CLI failed: ${detail}`
+        };
+      }
+
+      return {
+        ok: true,
+        state: CAPABILITY_STATES.AVAILABLE,
+        stdout: result.stdout,
+        stderr: result.stderr
+      };
+    }
+  };
+}
+
+function defaultProbe({ id, label, detected, cliAvailable, executable, versionArgs, authArgs }) {
+  let version = null;
+  let authenticated = null;
+  let probeError = null;
+  let authReady = false;
+
+  if (cliAvailable && executable) {
+    const versionResult = probeCommand(executable, versionArgs);
+    if (versionResult.timedOut || versionResult.error) {
+      probeError = versionResult.error ?? "probe timed out";
+    } else if (versionResult.ok) {
+      version = parseVersionFromOutput(versionResult.stdout) ?? versionResult.stdout.split("\n")[0] ?? null;
+    }
+
+    if (authArgs) {
+      const authResult = probeCommand(executable, authArgs);
+      if (authResult.timedOut || authResult.error) {
+        probeError = probeError ?? authResult.error ?? "auth probe timed out";
+      } else {
+        authenticated = authResult.ok;
+        authReady = authResult.ok;
+      }
+    } else if (version) {
+      authenticated = null;
+      authReady = true;
+    }
+  }
+
+  const state = resolveProbeState({
+    detected,
+    cliAvailable,
+    authReady,
+    probeError,
+    opaque: false
+  });
+
+  return buildInspection({
+    id,
+    label,
+    state,
+    detected,
+    cliAvailable,
+    version,
+    authenticated,
+    error: probeError,
+    recommendation: buildRecommendation({ label, state, detected, cliAvailable, authenticated })
+  });
+}
+
+function defaultProbeModels({ executable, modelsArgs }) {
+  const result = probeCommand(executable, modelsArgs);
+  if (!result.ok) return null;
+
+  const lines = result.stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  return lines.length > 0 ? lines : null;
+}
+
+function buildInspection(fields) {
+  return {
+    id: fields.id,
+    label: fields.label,
+    state: fields.state,
+    detected: fields.detected,
+    cliAvailable: fields.cliAvailable,
+    version: fields.version ?? null,
+    authenticated: fields.authenticated ?? null,
+    models: fields.models ?? null,
+    error: fields.error ?? null,
+    recommendation: fields.recommendation ?? null
+  };
+}
+
+function buildRecommendation({ label, state, detected, cliAvailable, authenticated }) {
+  if (state === CAPABILITY_STATES.ERROR) {
+    return `Re-run detection or check ${label} CLI logs for details.`;
+  }
+
+  if (state === CAPABILITY_STATES.UNKNOWN) {
+    return `Install ${label} or run ${formatCliCommand("detect")} after setup.`;
+  }
+
+  if (state === CAPABILITY_STATES.AVAILABLE) {
+    return `${label} is ready. Delegate tasks through its CLI.`;
+  }
+
+  if (authenticated === false) {
+    return `Authenticate with ${label} (provider login) before delegating work.`;
+  }
+
+  if (detected && !cliAvailable) {
+    return `${label} config detected but CLI not on PATH.`;
+  }
+
+  if (cliAvailable && !detected) {
+    return `${label} CLI found. Run ${formatCliCommand("setup")} to add managed sections.`;
+  }
+
+  return `${label} detected. Run ${formatCliCommand("status")} for ecosystem health.`;
+}
+
+function formatCliCommand(command) {
+  return `kairo ${command}`;
+}

package/src/global/agent-capabilities/index.js

@@ -0,0 +1,54 @@
+import cursorManaged from "../adapters/cursor.js";
+import codexManaged from "../adapters/codex.js";
+import opencodeManaged from "../adapters/opencode.js";
+import claudeManaged from "../adapters/claude.js";
+import { createAgentCapabilityAdapter } from "./create-capability-adapter.js";
+
+const cursor = createAgentCapabilityAdapter({
+  id: "cursor",
+  label: "Cursor",
+  managedAdapter: cursorManaged,
+  executable: "cursor",
+  opaqueAuth: true
+});
+
+const codex = createAgentCapabilityAdapter({
+  id: "codex",
+  label: "Codex",
+  managedAdapter: codexManaged,
+  executable: "codex",
+  runExecutable: "codex"
+});
+
+const opencode = createAgentCapabilityAdapter({
+  id: "opencode",
+  label: "OpenCode",
+  managedAdapter: opencodeManaged,
+  executable: "opencode",
+  runExecutable: "opencode"
+});
+
+const claude = createAgentCapabilityAdapter({
+  id: "claude",
+  label: "Claude Code",
+  managedAdapter: claudeManaged,
+  executable: "claude",
+  authArgs: ["auth", "status"],
+  runExecutable: "claude"
+});
+
+const CAPABILITY_ADAPTERS = [cursor, codex, opencode, claude];
+
+export const AGENT_CAPABILITY_IDS = CAPABILITY_ADAPTERS.map((adapter) => adapter.id);
+
+export function listCapabilityAdapters() {
+  return [...CAPABILITY_ADAPTERS];
+}
+
+export function resolveCapabilityAdapter(id) {
+  const adapter = CAPABILITY_ADAPTERS.find((candidate) => candidate.id === id);
+  if (!adapter) {
+    throw new Error(`Unknown agent capability "${id}". Use ${AGENT_CAPABILITY_IDS.join(", ")}.`);
+  }
+  return adapter;
+}

package/src/global/brand/cli.js

@@ -51,9 +51,9 @@ export function formatCliCommand(subcommand, cliName = PREFERRED_CLI) {
   return trimmed ? `${cliName} ${trimmed}` : cliName;
 }
 
-function detectInvocationPackageManager() {
-  const execPath = process.env.npm_execpath ?? "";
-  const userAgent = process.env.npm_config_user_agent ?? "";
+function detectInvocationPackageManager(env = process.env) {
+  const execPath = env.npm_execpath ?? "";
+  const userAgent = env.npm_config_user_agent ?? "";
 
   if (execPath.includes("pnpm") || userAgent.startsWith("pnpm/")) return "pnpm";
   if (execPath.includes("yarn") || userAgent.startsWith("yarn/")) return "yarn";
@@ -61,7 +61,11 @@ function detectInvocationPackageManager() {
   return "npm";
 }
 
-export function resolveSuggestedInvocation(packageName = PACKAGE_NAME, argv = process.argv) {
+export function resolveSuggestedInvocation(
+  packageName = PACKAGE_NAME,
+  argv = process.argv,
+  { env = process.env } = {}
+) {
   const invokedPath = argv[1] ?? PREFERRED_CLI;
   const invokedBase = basename(invokedPath);
 
@@ -69,7 +73,7 @@ export function resolveSuggestedInvocation(packageName = PACKAGE_NAME, argv = pr
     return invokedBase;
   }
 
-  const packageManager = detectInvocationPackageManager();
+  const packageManager = detectInvocationPackageManager(env);
 
   switch (packageManager) {
     case "pnpm":
@@ -85,9 +89,9 @@ export function resolveSuggestedInvocation(packageName = PACKAGE_NAME, argv = pr
 
 export function formatSuggestedCliCommand(
   subcommand,
-  { packageName = PACKAGE_NAME, argv = process.argv, suggestedInvocation } = {}
+  { packageName = PACKAGE_NAME, argv = process.argv, suggestedInvocation, env = process.env } = {}
 ) {
-  const invoke = suggestedInvocation ?? resolveSuggestedInvocation(packageName, argv);
+  const invoke = suggestedInvocation ?? resolveSuggestedInvocation(packageName, argv, { env });
   const trimmed = subcommand.trim();
   return trimmed ? `${invoke} ${trimmed}` : invoke;
 }

package/src/global/capability-registry.js

@@ -0,0 +1,80 @@
+import { buildAdapterContext } from "./adapter-context.js";
+import { CAPABILITY_STATES } from "./capability-states.js";
+import {
+  AGENT_CAPABILITY_IDS,
+  listCapabilityAdapters,
+  resolveCapabilityAdapter
+} from "./agent-capabilities/index.js";
+
+export async function inspectAllCapabilities({
+  homeDir,
+  workspaceRoot = process.cwd(),
+  packageName = "@kal-elsam/kairo-runtime",
+  probeOverrides = null
+} = {}) {
+  const context = buildAdapterContext({ homeDir, workspaceRoot, packageName });
+  const adapters = listCapabilityAdapters();
+
+  return Promise.all(adapters.map(async (adapter) => {
+    const probeOptions = probeOverrides?.[adapter.id] ?? {};
+    const inspection = adapter.inspect(context, probeOptions);
+    const models = adapter.listModels?.(context, probeOptions) ?? null;
+
+    return {
+      ...inspection,
+      models
+    };
+  }));
+}
+
+export async function inspectCapability(agentId, context, probeOptions = {}) {
+  const adapter = resolveCapabilityAdapter(agentId);
+  const inspection = adapter.inspect(context, probeOptions);
+  const models = adapter.listModels?.(context, probeOptions) ?? null;
+  return { ...inspection, models };
+}
+
+export function summarizeCapabilityRegistry(capabilities) {
+  const byState = {};
+  for (const state of Object.values(CAPABILITY_STATES)) {
+    byState[state] = 0;
+  }
+
+  for (const capability of capabilities) {
+    if (byState[capability.state] != null) {
+      byState[capability.state] += 1;
+    }
+  }
+
+  return {
+    total: capabilities.length,
+    supported: AGENT_CAPABILITY_IDS.length,
+    detected: capabilities.filter((entry) => entry.detected).length,
+    available: capabilities.filter((entry) => entry.state === CAPABILITY_STATES.AVAILABLE).length,
+    byState
+  };
+}
+
+export function buildCapabilityDiagnostics(capabilities) {
+  const recommendations = capabilities
+    .map((entry) => entry.recommendation)
+    .filter(Boolean);
+
+  const errors = capabilities
+    .filter((entry) => entry.state === CAPABILITY_STATES.ERROR)
+    .map((entry) => ({
+      agent: entry.id,
+      message: entry.error ?? entry.recommendation ?? "Inspection failed."
+    }));
+
+  return {
+    recommendations,
+    errors,
+    hasActionableErrors: errors.length > 0
+  };
+}
+
+export function delegateToAgent(agentId, context, runOptions = {}) {
+  const adapter = resolveCapabilityAdapter(agentId);
+  return adapter.run(context, runOptions);
+}

package/src/global/capability-states.js

@@ -0,0 +1,30 @@
+export const CAPABILITY_STATES = {
+  DETECTED: "detected",
+  AUTHENTICATED: "authenticated",
+  AVAILABLE: "available",
+  UNKNOWN: "unknown",
+  ERROR: "error"
+};
+
+export function isCapabilityState(value) {
+  return Object.values(CAPABILITY_STATES).includes(value);
+}
+
+export function formatCapabilityState(state) {
+  switch (state) {
+    case CAPABILITY_STATES.DETECTED:
+      return "detected";
+    case CAPABILITY_STATES.AUTHENTICATED:
+      return "authenticated";
+    case CAPABILITY_STATES.AVAILABLE:
+      return "available";
+    case CAPABILITY_STATES.UNKNOWN:
+      return "unknown";
+    case CAPABILITY_STATES.ERROR:
+      return "error";
+    default: {
+      const _exhaustive = state;
+      return String(_exhaustive);
+    }
+  }
+}

package/src/global/cli-probe.js

@@ -0,0 +1,47 @@
+import { spawnSync } from "node:child_process";
+
+const DEFAULT_TIMEOUT_MS = 5000;
+
+export function isExecutableAvailable(command, { env = process.env } = {}) {
+  const result = spawnSync("which", [command], { encoding: "utf8", env });
+  return result.status === 0 && result.stdout.trim().length > 0;
+}
+
+export function probeCommand(command, args = [], {
+  cwd = process.cwd(),
+  env = process.env,
+  timeoutMs = DEFAULT_TIMEOUT_MS
+} = {}) {
+  const result = spawnSync(command, args, {
+    cwd,
+    env,
+    encoding: "utf8",
+    timeout: timeoutMs
+  });
+
+  return {
+    ok: result.status === 0,
+    status: result.status,
+    stdout: (result.stdout ?? "").trim(),
+    stderr: (result.stderr ?? "").trim(),
+    error: result.error?.message ?? null,
+    timedOut: result.error?.code === "ETIMEDOUT"
+  };
+}
+
+export function parseVersionFromOutput(output) {
+  if (!output) return null;
+
+  const match = output.match(/(\d+\.\d+(?:\.\d+)?(?:[-+][\w.]+)?)/);
+  return match?.[1] ?? null;
+}
+
+export function resolveProbeState({ detected, cliAvailable, authReady, probeError, opaque = false }) {
+  if (probeError) return "error";
+  if (opaque) return "unknown";
+  if (!detected && !cliAvailable) return "unknown";
+  if (cliAvailable && authReady) return "available";
+  if (authReady) return "authenticated";
+  if (detected || cliAvailable) return "detected";
+  return "unknown";
+}

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

@@ -0,0 +1,209 @@
+import React, { useEffect, useState } from "react";
+import { Box, Text, useApp, useInput } from "ink";
+import { BRAND } from "../brand/index.js";
+import { PLAN_ACTIONS, buildActionPlan, buildReadOnlyDiagnostics } from "../action-planner.js";
+import { buildProfileJson, resolveProfile } from "../profile.js";
+import {
+  ORCHESTRATOR_MENU,
+  ORCHESTRATOR_VIEWS,
+  formatAgentStatusLines,
+  formatPlanLines,
+  formatProfileLines
+} from "./orchestrator-state.js";
+
+const COLORS = {
+  accent: "cyan",
+  success: "green",
+  warning: "yellow",
+  danger: "red",
+  muted: "gray"
+};
+
+export function OrchestratorApp({
+  homeDir,
+  workspaceRoot,
+  packageName,
+  packageRoot,
+  cliVersion,
+  onComplete
+}) {
+  const { exit } = useApp();
+  const [view, setView] = useState(ORCHESTRATOR_VIEWS.HOME);
+  const [menuIndex, setMenuIndex] = useState(0);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState(null);
+  const [diagnostics, setDiagnostics] = useState(null);
+  const [profileJson, setProfileJson] = useState(null);
+  const [plan, setPlan] = useState(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function load() {
+      try {
+        const [diag, profileResolved] = await Promise.all([
+          buildReadOnlyDiagnostics({ homeDir, workspaceRoot, packageName, packageRoot, cliVersion }),
+          resolveProfile({ homeDir, workspaceRoot })
+        ]);
+
+        if (cancelled) return;
+        setDiagnostics(diag);
+        setProfileJson(buildProfileJson(profileResolved));
+        setLoading(false);
+      } catch (loadError) {
+        if (cancelled) return;
+        setError(loadError instanceof Error ? loadError.message : String(loadError));
+        setLoading(false);
+      }
+    }
+
+    load();
+    return () => {
+      cancelled = true;
+    };
+  }, [homeDir, workspaceRoot, packageName, packageRoot, cliVersion]);
+
+  const finish = (outcome) => {
+    onComplete(outcome);
+    exit();
+  };
+
+  useInput((inputKey, key) => {
+    if (key.escape) {
+      if (view === ORCHESTRATOR_VIEWS.HOME) {
+        finish({ cancelled: true });
+        return;
+      }
+      setView(ORCHESTRATOR_VIEWS.HOME);
+      setPlan(null);
+      return;
+    }
+
+    if (loading || error) return;
+
+    if (view === ORCHESTRATOR_VIEWS.CONFIRM) {
+      if (inputKey.toLowerCase() === "y") {
+        finish({ cancelled: false, action: plan?.action ?? PLAN_ACTIONS.SETUP, confirmed: true, plan });
+      }
+      if (inputKey.toLowerCase() === "n") {
+        setView(ORCHESTRATOR_VIEWS.HOME);
+        setPlan(null);
+      }
+      return;
+    }
+
+    if (view !== ORCHESTRATOR_VIEWS.HOME) return;
+
+    if (key.upArrow) {
+      setMenuIndex((index) => Math.max(0, index - 1));
+      return;
+    }
+
+    if (key.downArrow) {
+      setMenuIndex((index) => Math.min(ORCHESTRATOR_MENU.length - 1, index + 1));
+      return;
+    }
+
+    if (!key.return) return;
+
+    const item = ORCHESTRATOR_MENU[menuIndex];
+    if (item.action === "setup") {
+      buildActionPlan({
+        action: PLAN_ACTIONS.SETUP,
+        homeDir,
+        workspaceRoot,
+        packageName,
+        options: { packageRoot, cliVersion }
+      }).then((builtPlan) => {
+        setPlan(builtPlan);
+        setView(ORCHESTRATOR_VIEWS.CONFIRM);
+      }).catch((planError) => {
+        setError(planError instanceof Error ? planError.message : String(planError));
+      });
+      return;
+    }
+
+    setView(item.view);
+  });
+
+  if (loading) {
+    return React.createElement(Box, { flexDirection: "column" },
+      React.createElement(Text, { bold: true, color: COLORS.accent }, BRAND.displayName),
+      React.createElement(Text, { color: COLORS.muted }, "Loading agent capabilities…")
+    );
+  }
+
+  if (error) {
+    return React.createElement(Box, { flexDirection: "column" },
+      React.createElement(Text, { bold: true, color: COLORS.danger }, "Orchestrator error"),
+      React.createElement(Text, null, error),
+      React.createElement(Text, { dimColor: true }, "Esc to exit")
+    );
+  }
+
+  return React.createElement(Box, { flexDirection: "column" },
+    React.createElement(Text, { bold: true, color: COLORS.accent }, `${BRAND.displayName} orchestrator`),
+    React.createElement(Text, { color: COLORS.muted }, "Provider-neutral agent coordinator · no model imposed"),
+    React.createElement(Text, null, ""),
+    renderView({ view, diagnostics, profileJson, plan, menuIndex }),
+    React.createElement(Text, null, ""),
+    React.createElement(Text, { dimColor: true }, footerHint(view))
+  );
+}
+
+function renderView({ view, diagnostics, profileJson, plan, menuIndex }) {
+  switch (view) {
+    case ORCHESTRATOR_VIEWS.HOME:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Menu"),
+        ORCHESTRATOR_MENU.map((item, index) =>
+          React.createElement(Text, {
+            key: item.id,
+            color: index === menuIndex ? COLORS.accent : undefined,
+            bold: index === menuIndex
+          }, `${index === menuIndex ? "› " : "  "}${item.label}`)
+        ),
+        React.createElement(Text, null, ""),
+        React.createElement(Text, { bold: true }, "Snapshot"),
+        React.createElement(Text, null, `Agents detected: ${diagnostics.diagnostics.detected}/${diagnostics.capabilities.length}`),
+        React.createElement(Text, null, `Available: ${diagnostics.diagnostics.available}`)
+      );
+    case ORCHESTRATOR_VIEWS.AGENTS:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Agent capabilities"),
+        formatAgentStatusLines(diagnostics.capabilities)
+          .map((line) => React.createElement(Text, { key: line }, line))
+      );
+    case ORCHESTRATOR_VIEWS.PROFILE:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Profile"),
+        formatProfileLines(profileJson)
+          .map((line) => React.createElement(Text, { key: line }, line))
+      );
+    case ORCHESTRATOR_VIEWS.PLAN:
+    case ORCHESTRATOR_VIEWS.CONFIRM:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, view === ORCHESTRATOR_VIEWS.CONFIRM ? "Confirm plan" : "Plan"),
+        plan && formatPlanLines(plan).map((line) => React.createElement(Text, { key: line }, line)),
+        view === ORCHESTRATOR_VIEWS.CONFIRM && React.createElement(Text, { color: COLORS.warning }, "Y confirm · N decline")
+      );
+    case ORCHESTRATOR_VIEWS.HELP:
+      return React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Text, { bold: true }, "Help"),
+        React.createElement(Text, null, "Kairo coordinates installed agent CLIs — it is not a coding model."),
+        React.createElement(Text, null, "Use explicit commands for scripts: setup, install, status, doctor, sync."),
+        React.createElement(Text, null, "Profiles: ~/.harness/profile.json and .harness/kairo.json (project wins)."),
+        React.createElement(Text, null, "Credentials are never stored by Kairo.")
+      );
+    default: {
+      const _exhaustive = view;
+      return React.createElement(Text, null, `Unknown view: ${_exhaustive}`);
+    }
+  }
+}
+
+function footerHint(view) {
+  if (view === ORCHESTRATOR_VIEWS.HOME) return "↑↓ navigate · Enter select · Esc quit";
+  if (view === ORCHESTRATOR_VIEWS.CONFIRM) return "Y confirm · N decline · Esc back";
+  return "Esc back to menu";
+}

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

@@ -0,0 +1,78 @@
+import { stdin as input, stdout as output } from "node:process";
+import { canUseSetupInk } from "./terminal.js";
+
+export function canUseOrchestratorShell({
+  interactive = Boolean(input.isTTY && output.isTTY),
+  term = process.env.TERM ?? "",
+  columns = output.columns ?? 80,
+  forceInk = process.env.HARNESS_INK !== "0"
+} = {}) {
+  return canUseSetupInk({ interactive, term, columns, forceInk });
+}
+
+export const ORCHESTRATOR_VIEWS = {
+  HOME: "home",
+  AGENTS: "agents",
+  PROFILE: "profile",
+  PLAN: "plan",
+  CONFIRM: "confirm",
+  HELP: "help"
+};
+
+export const ORCHESTRATOR_MENU = [
+  { id: "status", label: "Diagnostics", view: ORCHESTRATOR_VIEWS.HOME },
+  { id: "agents", label: "Agents", view: ORCHESTRATOR_VIEWS.AGENTS },
+  { id: "profile", label: "Profile", view: ORCHESTRATOR_VIEWS.PROFILE },
+  { id: "plan-setup", label: "Plan setup", view: ORCHESTRATOR_VIEWS.PLAN, action: "setup" },
+  { id: "help", label: "Help", view: ORCHESTRATOR_VIEWS.HELP }
+];
+
+export function formatAgentStatusLines(capabilities) {
+  return capabilities.map((entry) => {
+    const auth = entry.authenticated == null ? "n/a" : (entry.authenticated ? "yes" : "no");
+    const version = entry.version ?? "unknown";
+    return `${entry.label.padEnd(14)} ${entry.state.padEnd(14)} v${version} auth=${auth}`;
+  });
+}
+
+export function formatProfileLines(profileJson) {
+  const lines = [
+    `Coordinator: ${profileJson.coordinator ?? "none"}`,
+    `Default agents: ${formatAgentsLabel(profileJson.defaultAgents)}`,
+    `Apply mode: ${profileJson.applyMode}`
+  ];
+
+  if (profileJson.sources.global) {
+    lines.push(`Global: ${profileJson.sources.global}`);
+  }
+
+  if (profileJson.sources.project) {
+    lines.push(`Project: ${profileJson.sources.project}`);
+  }
+
+  lines.push(`Precedence: ${profileJson.sources.precedence}`);
+  return lines;
+}
+
+export function formatPlanLines(plan) {
+  const lines = [`Action: ${plan.action}`, ""];
+  for (const step of plan.steps) {
+    lines.push(`  • ${step}`);
+  }
+
+  if (plan.warnings.length > 0) {
+    lines.push("", "Warnings:");
+    for (const warning of plan.warnings) {
+      lines.push(`  ! ${warning}`);
+    }
+  }
+
+  return lines;
+}
+
+function formatAgentsLabel(agents) {
+  if (agents === "detected") return "detected";
+  if (agents === "all") return "all";
+  if (Array.isArray(agents)) return agents.join(", ");
+  return String(agents);
+}

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

@@ -0,0 +1,29 @@
+import React from "react";
+import { render } from "ink";
+import { OrchestratorApp } from "./orchestrator-app.js";
+
+export async function runOrchestratorInk({
+  homeDir,
+  workspaceRoot,
+  packageRoot,
+  packageName,
+  cliVersion,
+  renderImpl = render
+}) {
+  return new Promise((resolve) => {
+    const { waitUntilExit } = renderImpl(
+      React.createElement(OrchestratorApp, {
+        homeDir,
+        workspaceRoot,
+        packageRoot,
+        packageName,
+        cliVersion,
+        onComplete: resolve
+      })
+    );
+
+    waitUntilExit().catch((error) => {
+      resolve({ cancelled: true, error });
+    });
+  });
+}

package/src/global/orchestrator.js

@@ -0,0 +1,139 @@
+import { stdin as input, stdout as output } from "node:process";
+import { resolveHomeDir } from "./paths.js";
+import { runGlobalSetup } from "./global-cli.js";
+import { PLAN_ACTIONS, buildReadOnlyDiagnostics, shouldExecutePlan } from "./action-planner.js";
+import { canUseOrchestratorShell } from "./ink/orchestrator-state.js";
+import { runOrchestratorInk as defaultRunOrchestratorInk } from "./ink/run-orchestrator-ink.js";
+import { formatCliCommand } from "./brand/cli.js";
+import { BRAND } from "./brand/index.js";
+
+export { canUseOrchestratorShell };
+
+export function shouldOpenOrchestratorShell({
+  interactive = Boolean(input.isTTY && output.isTTY),
+  json = false,
+  hasImplicitFlags = false
+} = {}) {
+  if (!interactive || json) return false;
+  if (hasImplicitFlags) return false;
+  return canUseOrchestratorShell({ interactive });
+}
+
+export async function runOrchestratorShell({
+  packageRoot,
+  packageManifest,
+  workspaceRoot,
+  interactive = Boolean(input.isTTY && output.isTTY),
+  runOrchestratorInkImpl = defaultRunOrchestratorInk
+}) {
+  if (!interactive) {
+    throw new Error(
+      `Non-interactive shell requires an explicit command. Try ${formatCliCommand("help")} or ${formatCliCommand("setup --yes")}.`
+    );
+  }
+
+  if (!canUseOrchestratorShell({ interactive })) {
+    throw new Error(
+      `Interactive shell requires a capable TTY. Use ${formatCliCommand("setup --simple")} or explicit commands.`
+    );
+  }
+
+  const homeDir = resolveHomeDir();
+  const outcome = await runOrchestratorInkImpl({
+    homeDir,
+    workspaceRoot,
+    packageRoot,
+    packageName: packageManifest.name,
+    cliVersion: packageManifest.version
+  });
+
+  if (outcome.error) {
+    throw outcome.error;
+  }
+
+  if (outcome.cancelled) {
+    return { cancelled: true, wrote: false };
+  }
+
+  if (outcome.confirmed && outcome.action === PLAN_ACTIONS.SETUP) {
+    const setupOutcome = await runGlobalSetup(
+      {
+        cwd: workspaceRoot,
+        adapters: null,
+        components: null,
+        noDefaultComponents: false,
+        dryRun: false,
+        yes: false,
+        confirm: false,
+        preflight: true,
+        preflightExplicit: false,
+        yesExplicit: false,
+        confirmExplicit: false,
+        json: false,
+        interactive: true,
+        simple: false
+      },
+      packageManifest,
+      packageRoot
+    );
+
+    return {
+      cancelled: Boolean(setupOutcome.cancelled),
+      wrote: !setupOutcome.cancelled && !setupOutcome.result?.dryRun,
+      action: PLAN_ACTIONS.SETUP,
+      setupOutcome
+    };
+  }
+
+  return { cancelled: false, wrote: false, action: outcome.action ?? null };
+}
+
+export async function runOrchestratorDiagnostics({
+  homeDir,
+  workspaceRoot,
+  packageName,
+  packageRoot,
+  cliVersion,
+  json = false
+}) {
+  const diagnostics = await buildReadOnlyDiagnostics({
+    homeDir,
+    workspaceRoot,
+    packageName,
+    packageRoot,
+    cliVersion
+  });
+
+  if (json) {
+    return diagnostics;
+  }
+
+  console.log(commandHeader("orchestrator — agent capability diagnostics"));
+  console.log(`Home: ${homeDir}`);
+  console.log(`Workspace: ${workspaceRoot}`);
+  console.log("");
+
+  for (const capability of diagnostics.capabilities) {
+    console.log(
+      `  ${capability.label.padEnd(14)} ${capability.state.padEnd(14)} detected=${capability.detected ? "yes" : "no"}`
+    );
+  }
+
+  console.log("");
+  console.log("Recommendations:");
+  for (const recommendation of diagnostics.recommendations) {
+    console.log(`  - ${recommendation}`);
+  }
+
+  return diagnostics;
+}
+
+function commandHeader(title) {
+  return `${BRAND.displayName} ${title}`;
+}
+
+export function assertPlanExecution(plan, { confirmed = false } = {}) {
+  if (!shouldExecutePlan(plan, { confirmed })) {
+    throw new Error("Plan declined. No writes or installations were performed.");
+  }
+}

package/src/global/paths.js

@@ -15,6 +15,7 @@ export function harnessHomePaths(homeDir) {
     root,
     statePath: join(root, "state.json"),
     policyPath: join(root, "policy.json"),
+    profilePath: join(root, "profile.json"),
     historyPath: join(root, "history.jsonl"),
     coreDir: join(root, "core"),
     backupsDir: join(root, "backups")

package/src/global/profile.js

@@ -0,0 +1,146 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { harnessHomePaths } from "./paths.js";
+import { AGENT_CAPABILITY_IDS } from "./agent-capabilities/index.js";
+
+export const PROFILE_KEYS = new Set([
+  "coordinator",
+  "defaultAgents",
+  "defaultComponents",
+  "applyMode"
+]);
+
+export const DEFAULT_PROFILE = {
+  coordinator: null,
+  defaultAgents: "detected",
+  defaultComponents: null,
+  applyMode: "prompt"
+};
+
+const APPLY_MODES = new Set(["prompt", "confirm"]);
+
+export function getGlobalProfilePath(homeDir) {
+  return join(harnessHomePaths(homeDir).root, "profile.json");
+}
+
+export function getProjectProfilePath(workspaceRoot) {
+  return join(workspaceRoot, ".harness", "kairo.json");
+}
+
+export async function loadProfileFile(filePath) {
+  if (!existsSync(filePath)) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Invalid profile file at ${filePath}: ${error.message}`);
+  }
+
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Invalid profile file at ${filePath}: expected a JSON object.`);
+  }
+
+  return parsed;
+}
+
+export async function loadGlobalProfile(homeDir) {
+  return loadProfileFile(getGlobalProfilePath(homeDir));
+}
+
+export async function loadProjectProfile(workspaceRoot) {
+  return loadProfileFile(getProjectProfilePath(workspaceRoot));
+}
+
+export async function resolveProfile({ homeDir, workspaceRoot }) {
+  const globalRaw = await loadGlobalProfile(homeDir);
+  const projectRaw = await loadProjectProfile(workspaceRoot);
+
+  const merged = {
+    ...DEFAULT_PROFILE,
+    ...(globalRaw ?? {}),
+    ...(projectRaw ?? {})
+  };
+
+  validateProfile(merged);
+
+  return {
+    profile: merged,
+    sources: {
+      global: globalRaw ? getGlobalProfilePath(homeDir) : null,
+      project: projectRaw ? getProjectProfilePath(workspaceRoot) : null
+    }
+  };
+}
+
+export function buildProfileJson(resolved) {
+  const { profile, sources } = resolved;
+
+  return {
+    coordinator: profile.coordinator,
+    defaultAgents: profile.defaultAgents,
+    defaultComponents: profile.defaultComponents,
+    applyMode: profile.applyMode,
+    sources: {
+      global: sources.global,
+      project: sources.project,
+      precedence: "project overrides global overrides defaults"
+    }
+  };
+}
+
+export async function saveGlobalProfile(homeDir, profile) {
+  validateProfile(profile);
+  const { root } = harnessHomePaths(homeDir);
+  const profilePath = getGlobalProfilePath(homeDir);
+  await mkdir(root, { recursive: true });
+  await writeFile(profilePath, `${JSON.stringify(profile, null, 2)}\n`, "utf8");
+  return profilePath;
+}
+
+export function resolveProfileAgents(profile, detectedAgentIds) {
+  if (profile.defaultAgents === "detected") {
+    return detectedAgentIds.length > 0 ? [...detectedAgentIds] : [...AGENT_CAPABILITY_IDS];
+  }
+
+  if (profile.defaultAgents === "all") {
+    return [...AGENT_CAPABILITY_IDS];
+  }
+
+  if (Array.isArray(profile.defaultAgents)) {
+    return profile.defaultAgents.filter((id) => AGENT_CAPABILITY_IDS.includes(id));
+  }
+
+  return [...AGENT_CAPABILITY_IDS];
+}
+
+function validateProfile(profile) {
+  if (profile.coordinator != null && !AGENT_CAPABILITY_IDS.includes(profile.coordinator)) {
+    throw new Error(`Unknown coordinator "${profile.coordinator}". Use ${AGENT_CAPABILITY_IDS.join(", ")} or null.`);
+  }
+
+  if (!APPLY_MODES.has(profile.applyMode)) {
+    throw new Error(`Invalid applyMode "${profile.applyMode}". Use prompt or confirm.`);
+  }
+
+  if (
+    profile.defaultAgents !== "detected"
+    && profile.defaultAgents !== "all"
+    && !Array.isArray(profile.defaultAgents)
+  ) {
+    throw new Error('Profile defaultAgents must be "detected", "all", or an agent list.');
+  }
+
+  if (Array.isArray(profile.defaultAgents)) {
+    for (const agent of profile.defaultAgents) {
+      if (!AGENT_CAPABILITY_IDS.includes(agent)) {
+        throw new Error(`Unknown agent "${agent}" in profile.`);
+      }
+    }
+  }
+
+  if (profile.defaultComponents != null && !Array.isArray(profile.defaultComponents)) {
+    throw new Error("Profile defaultComponents must be an array or null.");
+  }
+}