@kal-elsam/kairo-runtime 0.1.3 → 0.1.5

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")