@kal-elsam/kairo-runtime 0.13.1 → 0.15.0

package/src/global/observability/fleet-probe.js

@@ -0,0 +1,229 @@
+/**
+ * Declared fleet topology (orchestrator → minions + models) + optional live activity.
+ * Read-only probes — writes go through fleet-set.js with consent.
+ */
+import { access, readFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
+import { join } from "node:path";
+import { resolveHomeDir } from "../paths.js";
+import { isExecutableAvailable } from "../cli-probe.js";
+import { buildOpenCodeActivity } from "./fleet-activity.js";
+import {
+  buildClaudeFleet,
+  buildCodexFleet,
+  buildCursorAgentsFleet
+} from "./fleet-platforms.js";
+
+const VARIANT_SUFFIX_RE = /-(?:cheap|zen)$/i;
+
+const MINION_ROLES = Object.freeze({
+  "sdd-apply": "executor",
+  "sdd-explore": "explorer",
+  "sdd-verify": "verifier",
+  "sdd-design": "designer",
+  "sdd-propose": "proposer",
+  "sdd-spec": "specifier",
+  "sdd-tasks": "planner",
+  "sdd-archive": "archiver",
+  "sdd-onboard": "onboarder",
+  "sdd-init": "initializer"
+});
+
+async function pathExists(path) {
+  try {
+    await access(path, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function shortModel(model) {
+  if (typeof model !== "string" || !model) return null;
+  const slash = model.lastIndexOf("/");
+  return slash >= 0 ? model.slice(slash + 1) : model;
+}
+
+function agentEntries(agents) {
+  if (!agents || typeof agents !== "object" || Array.isArray(agents)) return [];
+  return Object.entries(agents).map(([id, raw]) => ({
+    id: String(id),
+    mode: typeof raw?.mode === "string" ? raw.mode : null,
+    model: typeof raw?.model === "string" ? raw.model : null
+  }));
+}
+
+function pickOrchestrator(entries) {
+  const gentle = entries.find((e) => e.id === "gentle-orchestrator" && e.mode === "primary");
+  if (gentle) return gentle;
+  return entries.find((e) => e.mode === "primary") ?? null;
+}
+
+function isSddMinion(entry, { includeVariants = false } = {}) {
+  if (!entry?.id?.startsWith("sdd-")) return false;
+  if (entry.mode !== "subagent") return false;
+  if (!includeVariants && VARIANT_SUFFIX_RE.test(entry.id)) return false;
+  return true;
+}
+
+function minionRole(id) {
+  return MINION_ROLES[id] ?? (id.startsWith("sdd-") ? "specialist" : "minion");
+}
+
+export function parseOpenCodeFleet(config, { includeVariants = false } = {}) {
+  const defaultModel = typeof config?.model === "string" ? config.model : null;
+  const entries = agentEntries(config?.agent ?? config?.agents);
+  if (entries.length === 0) {
+    return {
+      platform: "opencode",
+      orchestrator: null,
+      minions: [],
+      opaque: false,
+      writable: true,
+      source: "opencode.json"
+    };
+  }
+
+  const orch = pickOrchestrator(entries);
+  const orchModel = orch?.model ?? defaultModel;
+  const minions = entries
+    .filter((e) => isSddMinion(e, { includeVariants }))
+    .map((e) => {
+      const model = e.model ?? defaultModel;
+      return {
+        id: e.id,
+        model,
+        modelShort: shortModel(model),
+        role: minionRole(e.id),
+        mode: e.mode
+      };
+    })
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  return {
+    platform: "opencode",
+    orchestrator: orch
+      ? {
+          id: orch.id,
+          model: orchModel,
+          modelShort: shortModel(orchModel),
+          mode: orch.mode ?? "primary",
+          opaque: false
+        }
+      : null,
+    minions,
+    opaque: false,
+    writable: true,
+    source: "opencode.json"
+  };
+}
+
+async function readJson(path, read = readFile) {
+  try {
+    return JSON.parse(await read(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function buildFleetReport({
+  homeDir = resolveHomeDir(),
+  includeVariants = false,
+  includeActivity = true,
+  read = readFile,
+  exists = pathExists,
+  gentleAvailable = () => isExecutableAvailable("gentle-ai"),
+  buildActivity = buildOpenCodeActivity,
+  buildClaude = buildClaudeFleet,
+  buildCodex = buildCodexFleet,
+  buildCursor = buildCursorAgentsFleet
+} = {}) {
+  const fleets = [];
+  const openCodePath = join(homeDir, ".config", "opencode", "opencode.json");
+  if (await exists(openCodePath)) {
+    const config = await readJson(openCodePath, read);
+    if (config) {
+      const fleet = parseOpenCodeFleet(config, { includeVariants });
+      fleet.configPath = openCodePath;
+      fleets.push(fleet);
+    }
+  }
+
+  if (await exists(join(homeDir, ".cursor"))) {
+    fleets.push(await buildCursor({ homeDir, read }));
+  }
+
+  if (await exists(join(homeDir, ".claude"))) {
+    const fleet = await buildClaude({ homeDir, read });
+    if (fleet) fleets.push(fleet);
+  }
+
+  if (await exists(join(homeDir, ".codex"))) {
+    const fleet = await buildCodex({ homeDir, read });
+    if (fleet) fleets.push(fleet);
+  }
+
+  const activity = includeActivity
+    ? await buildActivity({ homeDir })
+    : null;
+
+  return {
+    ok: true,
+    kind: "declared+activity",
+    note: "Declared config topology + OpenCode live activity when available.",
+    orchestratorAuthority: gentleAvailable() ? "gentle-ai" : null,
+    fleets,
+    activity,
+    generatedAt: new Date().toISOString()
+  };
+}
+
+export function formatFleetText(report, { verbose = false } = {}) {
+  const lines = ["Fleet floor", ""];
+  if (report.orchestratorAuthority) {
+    lines.push(`Authority · ${report.orchestratorAuthority}`);
+    lines.push("");
+  }
+  for (const fleet of report.fleets ?? []) {
+    const orch = fleet.orchestrator;
+    const modelBit = orch?.opaque
+      ? "opaque · IDE-managed"
+      : (orch?.modelShort ?? orch?.model ?? "—");
+    const minionCount = (fleet.minions ?? []).length;
+    lines.push(`${fleet.platform} · ${orch?.id ?? "—"} · ${modelBit}`);
+    if (verbose) {
+      for (const m of fleet.minions ?? []) {
+        const opaque = m.opaque ? " · opaque" : "";
+        lines.push(`  ${m.id} · ${m.modelShort ?? m.model ?? "—"} · ${m.role}${opaque}`);
+      }
+      if (fleet.note) lines.push(`  note: ${fleet.note}`);
+    } else if (minionCount > 0) {
+      lines.push(`  ${minionCount} minions · kairo fleet --verbose`);
+    }
+    lines.push("");
+  }
+
+  const act = report.activity;
+  if (act?.available) {
+    const active = (act.agents ?? []).filter((a) => a.state === "active");
+    if (active.length === 0) {
+      lines.push("Working floor · quiet (no live OpenCode sessions)");
+      lines.push("");
+    } else {
+      lines.push(`Working floor · ${active.length} live`);
+      for (const a of active) {
+        lines.push(`  ● ${a.id} · ${a.modelShort ?? a.model ?? "—"}`);
+      }
+      lines.push("");
+    }
+  } else if (act && !act.available) {
+    lines.push(`Working floor · unavailable`);
+    lines.push("");
+  }
+
+  if ((report.fleets ?? []).length === 0) {
+    lines.push("No agent platforms detected.");
+  }
+  lines.push(report.note ?? "");
+  return lines.join("\n").trimEnd();
+}

package/src/global/paths.js

@@ -23,7 +23,8 @@ export function harnessHomePaths(homeDir) {
     monitorDir: join(root, "monitor"),
     monitorStatePath: join(root, "monitor", "state.json"),
     coreDir: join(root, "core"),
-    backupsDir: join(root, "backups")
+    backupsDir: join(root, "backups"),
+    sessionsDir: join(root, "sessions")
   };
 }
 

package/src/global/self-update.js

@@ -0,0 +1,216 @@
+import { spawn } from "node:child_process";
+import { fetchPublishedVersion } from "./npm-registry.js";
+import { formatCliCommand } from "./brand/cli.js";
+import { commandHeader } from "./brand/index.js";
+
+/**
+ * @param {string} version
+ * @returns {number[]}
+ */
+export function parseSemver(version) {
+  const match = String(version).trim().match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+
+/**
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1|null}
+ */
+export function compareSemver(a, b) {
+  const left = parseSemver(a);
+  const right = parseSemver(b);
+  if (!left || !right) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (left[i] < right[i]) return -1;
+    if (left[i] > right[i]) return 1;
+  }
+  return 0;
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {"npm"|"pnpm"|"yarn"|"bun"}
+ */
+export function detectInstallPackageManager(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";
+  if (execPath.includes("bun") || userAgent.startsWith("bun/")) return "bun";
+  return "npm";
+}
+
+/**
+ * @param {string} packageName
+ * @param {string} version
+ * @param {"npm"|"pnpm"|"yarn"|"bun"} manager
+ * @returns {{ command: string, args: string[], display: string }}
+ */
+export function buildGlobalInstallSpec(packageName, version, manager = "npm") {
+  const spec = `${packageName}@${version}`;
+  switch (manager) {
+    case "pnpm":
+      return {
+        command: "pnpm",
+        args: ["add", "-g", spec],
+        display: `pnpm add -g ${spec}`
+      };
+    case "yarn":
+      return {
+        command: "yarn",
+        args: ["global", "add", spec],
+        display: `yarn global add ${spec}`
+      };
+    case "bun":
+      return {
+        command: "bun",
+        args: ["add", "-g", spec],
+        display: `bun add -g ${spec}`
+      };
+    default:
+      return {
+        command: "npm",
+        args: ["install", "-g", spec],
+        display: `npm install -g ${spec}`
+      };
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {string} options.packageName
+ * @param {string} options.cliVersion
+ * @param {boolean} [options.yes]
+ * @param {boolean} [options.json]
+ * @param {typeof fetchPublishedVersion} [options.fetchVersion]
+ * @param {typeof detectInstallPackageManager} [options.detectManager]
+ * @param {(cmd: string, args: string[]) => Promise<{ status: number, stdout: string, stderr: string }>} [options.runCommand]
+ */
+export async function runSelfUpdate({
+  packageName,
+  cliVersion,
+  yes = false,
+  json = false,
+  fetchVersion = fetchPublishedVersion,
+  detectManager = detectInstallPackageManager,
+  runCommand = defaultRunCommand
+} = {}) {
+  if (!packageName) throw new Error("packageName is required.");
+  if (!cliVersion) throw new Error("cliVersion is required.");
+
+  const latestVersion = await fetchVersion(packageName);
+  const cmp = compareSemver(cliVersion, latestVersion);
+  const manager = detectManager();
+  const install = buildGlobalInstallSpec(packageName, latestVersion, manager);
+
+  /** @type {"current"|"behind"|"ahead"|"unknown"} */
+  let state = "unknown";
+  if (cmp === 0) state = "current";
+  else if (cmp === -1) state = "behind";
+  else if (cmp === 1) state = "ahead";
+
+  const report = {
+    ok: true,
+    state,
+    installedVersion: cliVersion,
+    latestVersion,
+    packageName,
+    manager,
+    installCommand: install.display,
+    applied: false,
+    wrote: false
+  };
+
+  if (state === "current") {
+    report.nextAction = "Already up to date.";
+  } else if (state === "ahead") {
+    report.nextAction = `Local ${cliVersion} is newer than npm ${latestVersion}.`;
+  } else if (state === "behind") {
+    report.nextAction = yes
+      ? `Updating ${cliVersion} → ${latestVersion}…`
+      : `Update available: ${cliVersion} → ${latestVersion}. Run "${formatCliCommand("update --yes")}" or: ${install.display}`;
+  } else {
+    report.nextAction = `Could not compare versions. Install manually: ${install.display}`;
+  }
+
+  if (json) {
+    if (yes && state === "behind") {
+      const result = await runCommand(install.command, install.args);
+      report.applied = result.status === 0;
+      report.wrote = result.status === 0;
+      report.ok = result.status === 0;
+      report.installStatus = result.status;
+      report.stderr = result.stderr.trim() || undefined;
+      report.nextAction = result.status === 0
+        ? `Updated to ${latestVersion}.`
+        : `Install failed (exit ${result.status}). Try: ${install.display}`;
+    }
+    console.log(JSON.stringify(report));
+    return report;
+  }
+
+  console.log(commandHeader("update — Kairo Runtime"));
+  console.log(`Installed: ${cliVersion}`);
+  console.log(`Latest:    ${latestVersion}`);
+  console.log(`Status:    ${state}`);
+
+  if (state === "current") {
+    console.log("\nAlready up to date.");
+    return report;
+  }
+
+  if (state === "ahead") {
+    console.log(`\n${report.nextAction}`);
+    return report;
+  }
+
+  if (!yes) {
+    console.log(`\nUpdate available: ${cliVersion} → ${latestVersion}`);
+    console.log(`Run: ${formatCliCommand("update --yes")}`);
+    console.log(`Or:  ${install.display}`);
+    return report;
+  }
+
+  console.log(`\nInstalling ${install.display}…`);
+  const result = await runCommand(install.command, install.args);
+  report.applied = result.status === 0;
+  report.wrote = result.status === 0;
+  report.ok = result.status === 0;
+  report.installStatus = result.status;
+  if (result.stdout.trim()) console.log(result.stdout.trim());
+  if (result.stderr.trim()) console.error(result.stderr.trim());
+  if (result.status !== 0) {
+    throw new Error(`Self-update failed (exit ${result.status}). Try: ${install.display}`);
+  }
+  console.log(`\nUpdated to ${latestVersion}. Run "${formatCliCommand("--version")}" to confirm.`);
+  report.nextAction = `Updated to ${latestVersion}.`;
+  return report;
+}
+
+function defaultRunCommand(command, args) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: false,
+      env: process.env
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) => {
+      resolve({ status: 1, stdout, stderr: error.message });
+    });
+    child.on("close", (code) => {
+      resolve({ status: code ?? 1, stdout, stderr });
+    });
+  });
+}