@kal-elsam/kairo-runtime 0.14.0 → 0.16.0

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

@@ -0,0 +1,166 @@
+/**
+ * Declared fleets for Claude / Codex / Cursor agents (public configs only).
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+export function parseFrontmatterModel(raw) {
+  const text = String(raw ?? "");
+  const match = text.match(FRONTMATTER_RE);
+  if (!match) return { model: null, name: null };
+  const block = match[1];
+  const modelLine = block.match(/^model:\s*(.+)$/m);
+  const nameLine = block.match(/^name:\s*(.+)$/m);
+  const model = modelLine ? modelLine[1].trim().replace(/^["']|["']$/g, "") : null;
+  const name = nameLine ? nameLine[1].trim().replace(/^["']|["']$/g, "") : null;
+  return { model, name };
+}
+
+export function replaceFrontmatterModel(raw, nextModel) {
+  const text = String(raw ?? "");
+  const match = text.match(FRONTMATTER_RE);
+  if (!match) {
+    throw new Error("Agent file has no YAML frontmatter to update.");
+  }
+  const block = match[1];
+  let nextBlock;
+  if (/^model:\s*.+$/m.test(block)) {
+    nextBlock = block.replace(/^model:\s*.+$/m, `model: ${nextModel}`);
+  } else {
+    nextBlock = `${block.trimEnd()}\nmodel: ${nextModel}`;
+  }
+  return text.replace(FRONTMATTER_RE, `---\n${nextBlock}\n---`);
+}
+
+export function parseCodexDefaultModel(tomlText) {
+  const match = String(tomlText ?? "").match(/^\s*model\s*=\s*"([^"]+)"/m);
+  return match ? match[1] : null;
+}
+
+export function replaceCodexDefaultModel(tomlText, nextModel) {
+  const text = String(tomlText ?? "");
+  if (!/^\s*model\s*=\s*"[^"]*"/m.test(text)) {
+    throw new Error("Codex config.toml has no top-level model = \"...\" line.");
+  }
+  return text.replace(/^\s*model\s*=\s*"[^"]*"/m, `model = "${nextModel}"`);
+}
+
+function minionRole(id) {
+  if (id === "sdd-apply") return "executor";
+  if (id === "sdd-explore") return "explorer";
+  if (id === "sdd-verify") return "verifier";
+  return id.startsWith("sdd-") ? "specialist" : "minion";
+}
+
+async function listAgentFiles(dir, read = readFile, list = readdir) {
+  try {
+    const names = await list(dir);
+    const out = [];
+    for (const name of names) {
+      if (!name.endsWith(".md")) continue;
+      const path = join(dir, name);
+      const raw = await read(path, "utf8");
+      const meta = parseFrontmatterModel(raw);
+      const id = meta.name || name.replace(/\.md$/, "");
+      if (!id.startsWith("sdd-")) continue;
+      out.push({
+        id,
+        model: meta.model,
+        modelShort: meta.model,
+        role: minionRole(id),
+        mode: "subagent",
+        path,
+        opaque: meta.model === "inherit" || meta.model == null
+      });
+    }
+    return out.sort((a, b) => a.id.localeCompare(b.id));
+  } catch {
+    return [];
+  }
+}
+
+export async function buildClaudeFleet({ homeDir, read = readFile, list = readdir } = {}) {
+  const settingsPath = join(homeDir, ".claude", "settings.json");
+  let defaultModel = null;
+  try {
+    const settings = JSON.parse(await read(settingsPath, "utf8"));
+    defaultModel = typeof settings?.model === "string" ? settings.model : null;
+  } catch {
+    defaultModel = null;
+  }
+  const minions = await listAgentFiles(join(homeDir, ".claude", "agents"), read, list);
+  return {
+    platform: "claude",
+    orchestrator: {
+      id: "default",
+      model: defaultModel,
+      modelShort: defaultModel,
+      mode: "primary",
+      opaque: false
+    },
+    minions: minions.map((m) => ({
+      ...m,
+      model: m.model ?? defaultModel,
+      modelShort: m.modelShort ?? defaultModel,
+      opaque: false
+    })),
+    opaque: false,
+    writable: true,
+    note: "Declared Claude settings + agent frontmatter models.",
+    source: "claude"
+  };
+}
+
+export async function buildCodexFleet({ homeDir, read = readFile } = {}) {
+  const configPath = join(homeDir, ".codex", "config.toml");
+  let model = null;
+  try {
+    model = parseCodexDefaultModel(await read(configPath, "utf8"));
+  } catch {
+    model = null;
+  }
+  return {
+    platform: "codex",
+    orchestrator: {
+      id: "default",
+      model,
+      modelShort: model,
+      mode: "primary",
+      opaque: model == null
+    },
+    minions: [],
+    opaque: model == null,
+    writable: true,
+    configPath,
+    note: "Codex default model from ~/.codex/config.toml (no parent→child live topology).",
+    source: "codex"
+  };
+}
+
+export async function buildCursorAgentsFleet({ homeDir, read = readFile, list = readdir } = {}) {
+  const minions = await listAgentFiles(join(homeDir, ".cursor", "agents"), read, list);
+  return {
+    platform: "cursor",
+    orchestrator: {
+      id: "auto",
+      model: null,
+      modelShort: null,
+      mode: "primary",
+      opaque: true
+    },
+    minions: minions.map((m) => ({
+      id: m.id,
+      model: m.model,
+      modelShort: m.modelShort,
+      role: m.role,
+      mode: "subagent",
+      opaque: true
+    })),
+    opaque: true,
+    writable: false,
+    note: "Cursor Auto is IDE-managed. Subagents typically use model: inherit — change models in Cursor UI.",
+    source: "cursor-agents"
+  };
+}

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/observability/gentle-probe.js

@@ -7,8 +7,15 @@ import {
 import { normalizeProbeResult } from "./probe-contract.js";
 
 export const SUPPORTED_PROTOCOL = Object.freeze({ major: 2, minor: 0 });
+export const SUPPORTED_PROTOCOL_MINORS = Object.freeze([0, 1]);
 export const SUPPORTED_SCHEMA = "gentle-ai.review-integration.capabilities/v2";
+export const SUPPORTED_SCHEMA_V21 = "gentle-ai.review-integration.capabilities/v2.1";
+export const SUPPORTED_CAPABILITY_SCHEMAS = Object.freeze([
+  SUPPORTED_SCHEMA,
+  SUPPORTED_SCHEMA_V21
+]);
 export const SUPPORTED_CONTRACT = "gentle-ai.review-integration/v2";
+export const ADDITIVE_MINOR_POLICY = "optional-fields-only";
 export const SUPPORTED_MANDATORY_FEATURES = Object.freeze([
   "compact_v2_authority", "exact_receipt_replay", "five_delivery_gates",
   "immutable_snapshot", "legacy_v1_target_scoped_read_only",
@@ -51,7 +58,7 @@ export function evaluateGentleCapabilities(payload) {
       diagnostics: ["Capabilities payload is not an object."]
     });
   }
-  if (payload.schema !== SUPPORTED_SCHEMA) {
+  if (!SUPPORTED_CAPABILITY_SCHEMAS.includes(payload.schema)) {
     diagnostics.push(`schema mismatch: got ${String(payload.schema)}`);
   }
   if (payload.contract !== SUPPORTED_CONTRACT) {
@@ -60,9 +67,30 @@ export function evaluateGentleCapabilities(payload) {
   if (payload.protocol?.major !== SUPPORTED_PROTOCOL.major) {
     diagnostics.push(`protocol.major mismatch: got ${String(payload.protocol?.major)}`);
   }
-  if (payload.protocol?.minor !== SUPPORTED_PROTOCOL.minor) {
+  if (!SUPPORTED_PROTOCOL_MINORS.includes(payload.protocol?.minor)) {
     diagnostics.push(`protocol.minor mismatch: got ${String(payload.protocol?.minor)}`);
   }
+  const additivePolicy = payload.compatibility?.additive_minor_policy;
+  if (additivePolicy != null && additivePolicy !== ADDITIVE_MINOR_POLICY) {
+    diagnostics.push(`additive_minor_policy mismatch: got ${String(additivePolicy)}`);
+  }
+  if (typeof payload.bootstrap?.command === "string" && payload.bootstrap.command) {
+    evidence.push({
+      kind: "bootstrap",
+      command: payload.bootstrap.command,
+      required_feature: payload.bootstrap.required_feature ?? null
+    });
+  }
+  const requiredFeature = payload.bootstrap?.required_feature;
+  if (typeof requiredFeature === "string" && requiredFeature) {
+    const named = [
+      ...(Array.isArray(payload.features?.mandatory) ? payload.features.mandatory : []),
+      ...(Array.isArray(payload.features?.optional) ? payload.features.optional : [])
+    ];
+    if (!named.some((feature) => feature?.name === requiredFeature && feature.supported === true)) {
+      diagnostics.push(`bootstrap required_feature not supported: ${requiredFeature}`);
+    }
+  }
   const mandatory = payload.features?.mandatory;
   if (!Array.isArray(mandatory)) {
     diagnostics.push("features.mandatory must be an array.");

package/src/global/observability/index.js

@@ -24,7 +24,8 @@ export {
   runPassiveObservabilitySnapshot
 } from "./passive-snapshot-flight.js";
 export {
-  SUPPORTED_PROTOCOL, SUPPORTED_SCHEMA, SUPPORTED_CONTRACT,
+  SUPPORTED_PROTOCOL, SUPPORTED_PROTOCOL_MINORS, SUPPORTED_SCHEMA, SUPPORTED_SCHEMA_V21,
+  SUPPORTED_CAPABILITY_SCHEMAS, SUPPORTED_CONTRACT, ADDITIVE_MINOR_POLICY,
   SUPPORTED_MANDATORY_FEATURES, evaluateGentleCapabilities, probeGentle, createGentleProbe,
   resolveGentleBinaryPath
 } from "./gentle-probe.js";

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