@kal-elsam/kairo-runtime 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.1.3",
+  "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/scripts/install.sh

@@ -184,7 +184,7 @@ require_cmd npm
 NODE_VERSION="$(node --version 2>/dev/null || true)"
 NPM_VERSION="$(npm --version 2>/dev/null || true)"
 GLOBAL_SPEC="$(resolve_global_spec)"
-GLOBAL_INSTALL_CMD="npm install -g ${GLOBAL_SPEC}"
+GLOBAL_INSTALL_CMD="npm install -g --force ${GLOBAL_SPEC}"
 SETUP_CMD="${PREFERRED_CLI} setup ${SETUP_MODE}${SETUP_EXTRA:+ ${SETUP_EXTRA}}"
 
 printf '%s\n' \
@@ -224,7 +224,7 @@ fi
 
 printf '%s\n' "Installing global CLI..." ""
 # shellcheck disable=SC2086
-npm install -g ${GLOBAL_SPEC}
+npm install -g --force ${GLOBAL_SPEC}
 
 KAIRO_BIN="$(resolve_kairo_bin || true)"
 if [ -z "$KAIRO_BIN" ]; then

package/scripts/lib/install-script-url.mjs

@@ -2,6 +2,31 @@ import { fileURLToPath } from "node:url";
 import path from "node:path";
 
 const DEFAULT_REPO = "Kal-elSam/harness";
+const LEGACY_HARNESS_MINOR_CUTOFF = 29;
+
+function parseSemver(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-.+)?$/.exec(version);
+
+  if (!match) {
+    return null;
+  }
+
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3])
+  };
+}
+
+export function usesLegacyHarnessTag(version) {
+  const semver = parseSemver(version);
+
+  if (!semver) {
+    return false;
+  }
+
+  return semver.major === 0 && semver.minor >= LEGACY_HARNESS_MINOR_CUTOFF;
+}
 
 export function resolveInstallScriptRef({ version, tag = null }) {
   if (version === "latest") {
@@ -12,7 +37,11 @@ export function resolveInstallScriptRef({ version, tag = null }) {
     return tag;
   }
 
-  return `v${version}`;
+  if (usesLegacyHarnessTag(version)) {
+    return `v${version}`;
+  }
+
+  return `kairo-runtime-v${version}`;
 }
 
 export function resolveInstallScriptUrl({

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