@kal-elsam/kairo-runtime 0.4.2 → 0.5.0

package/src/global/intelligence-cli.js

@@ -9,12 +9,14 @@ import {
 } from "./intelligence/index.js";
 import { BRAND } from "./brand/index.js";
 import { formatCliCommand } from "./brand/cli.js";
+import { resolveSessionOverride } from "./intelligence-session.js";
 
 export async function runIntelligenceCli(options, packageManifest) {
   const action = options.intelligenceAction ?? "status";
   const homeDir = resolveHomeDir();
   const workspaceRoot = options.cwd;
   const { profile, sources } = await resolveProfile({ homeDir, workspaceRoot });
+  const sessionOverride = resolveSessionOverride(options);
 
   switch (action) {
     case "status":
@@ -24,13 +26,15 @@ export async function runIntelligenceCli(options, packageManifest) {
         profile,
         sources,
         json: options.json,
-        env: process.env
+        env: process.env,
+        sessionOverride
       });
     case "models":
       return printIntelligenceModels({
         profile,
         json: options.json,
-        env: process.env
+        env: process.env,
+        sessionOverride
       });
     case "context":
       return printIntelligenceContext({
@@ -49,7 +53,8 @@ export async function runIntelligenceCli(options, packageManifest) {
         task: options.intelligenceTask,
         cloudConsent: options.cloudConsent,
         json: options.json,
-        env: process.env
+        env: process.env,
+        sessionOverride
       });
     case "ask":
       return runIntelligenceAsk({
@@ -63,7 +68,8 @@ export async function runIntelligenceCli(options, packageManifest) {
         confirmed: options.yes || options.confirm,
         json: options.json,
         env: process.env,
-        packageManifest
+        packageManifest,
+        sessionOverride
       });
     default:
       throw new Error(
@@ -72,7 +78,15 @@ export async function runIntelligenceCli(options, packageManifest) {
   }
 }
 
-async function printIntelligenceStatus({ homeDir, workspaceRoot, profile, sources, json, env }) {
+async function printIntelligenceStatus({
+  homeDir,
+  workspaceRoot,
+  profile,
+  sources,
+  json,
+  env,
+  sessionOverride
+}) {
   const backends = await inspectIntelligenceBackends({
     env,
     customProviders: profile.customProviders
@@ -81,7 +95,8 @@ async function printIntelligenceStatus({ homeDir, workspaceRoot, profile, source
   const routing = resolveRoutingDecision({
     backends,
     profile,
-    cloudConsent: false
+    cloudConsent: false,
+    sessionOverride
   });
 
   const payload = {
@@ -89,6 +104,7 @@ async function printIntelligenceStatus({ homeDir, workspaceRoot, profile, source
     homeDir,
     workspaceRoot,
     profile: buildProfileJson({ profile, sources }),
+    sessionOverride,
     backends,
     summary,
     routing
@@ -119,13 +135,17 @@ async function printIntelligenceStatus({ homeDir, workspaceRoot, profile, source
   return payload;
 }
 
-async function printIntelligenceModels({ profile, json, env }) {
+async function printIntelligenceModels({ profile, json, env, sessionOverride }) {
   const backends = await inspectIntelligenceBackends({
     env,
     customProviders: profile.customProviders
   });
+  const filterId = sessionOverride?.preferredBackend ?? null;
+  const filtered = filterId
+    ? backends.filter((backend) => backend.id === filterId)
+    : backends;
 
-  const models = backends.flatMap((backend) =>
+  const models = filtered.flatMap((backend) =>
     (backend.models ?? []).map((model) => ({
       ...model,
       backendState: backend.state,
@@ -133,11 +153,16 @@ async function printIntelligenceModels({ profile, json, env }) {
     }))
   );
 
-  const payload = { readOnly: true, models, backends: backends.map((entry) => ({
-    id: entry.id,
-    state: entry.state,
-    available: entry.available
-  })) };
+  const payload = {
+    readOnly: true,
+    sessionOverride,
+    models,
+    backends: filtered.map((entry) => ({
+      id: entry.id,
+      state: entry.state,
+      available: entry.available
+    }))
+  };
 
   if (json) {
     console.log(JSON.stringify(payload, null, 2));
@@ -219,7 +244,8 @@ async function printIntelligenceRoute({
   task,
   cloudConsent,
   json,
-  env
+  env,
+  sessionOverride
 }) {
   const backends = await inspectIntelligenceBackends({
     env,
@@ -231,11 +257,13 @@ async function printIntelligenceRoute({
     profile,
     contextPack: pack,
     task,
-    cloudConsent: Boolean(cloudConsent)
+    cloudConsent: Boolean(cloudConsent),
+    sessionOverride
   });
 
   const payload = {
     readOnly: true,
+    sessionOverride,
     routing,
     estimatedTokens: pack.estimatedTokens,
     evidenceUsed: pack.evidence.filter((entry) => entry.kind === "file").map((entry) => entry.path)
@@ -266,7 +294,8 @@ async function runIntelligenceAsk({
   cloudConsent,
   confirmed,
   json,
-  env
+  env,
+  sessionOverride
 }) {
   if (!prompt && !task) {
     throw new Error(`Missing prompt. Use: ${formatCliCommand("intelligence ask --prompt \"...\"")}`);
@@ -281,7 +310,8 @@ async function runIntelligenceAsk({
     includePrivate,
     cloudConsent,
     confirmed,
-    env
+    env,
+    sessionOverride
   });
 
   if (json) {
@@ -289,6 +319,7 @@ async function runIntelligenceAsk({
       ok: outcome.ok,
       mode: outcome.mode,
       diagnosticsOnly: outcome.diagnosticsOnly,
+      sessionOverride,
       routing: outcome.routing,
       explanation: outcome.explanation,
       telemetry: outcome.telemetry,

package/src/global/intelligence-session.js

@@ -0,0 +1,37 @@
+import { BACKEND_IDS } from "./intelligence/index.js";
+
+const EPHEMERAL_BACKENDS = new Set([
+  BACKEND_IDS.OLLAMA,
+  BACKEND_IDS.OPENROUTER,
+  BACKEND_IDS.OPENCODE_GO,
+  BACKEND_IDS.OPENCODE_ZEN,
+  BACKEND_IDS.OPENCODE
+]);
+
+const BACKEND_HINT =
+  "Use opencode-go, opencode-zen, opencode, ollama, or openrouter.";
+
+/**
+ * Resolve ephemeral CLI --backend/--model overrides.
+ * Does not read or write profiles; credentials stay in env.
+ */
+export function resolveSessionOverride(options = {}) {
+  if (options.intelligenceBackend != null && String(options.intelligenceBackend).trim() === "") {
+    throw new Error(`Missing --backend value. ${BACKEND_HINT}`);
+  }
+
+  const preferredBackend = options.intelligenceBackend == null
+    ? null
+    : String(options.intelligenceBackend).trim();
+  const preferredModel = options.model == null || String(options.model).trim() === ""
+    ? null
+    : String(options.model).trim();
+
+  if (!preferredBackend && !preferredModel) return null;
+
+  if (preferredBackend && !EPHEMERAL_BACKENDS.has(preferredBackend)) {
+    throw new Error(`Unknown --backend "${preferredBackend}". ${BACKEND_HINT}`);
+  }
+
+  return { preferredBackend, preferredModel };
+}

package/src/global/json-output.js

@@ -8,6 +8,7 @@ export function buildControlPlaneJson(report, { cliVersion, extras = {} } = {})
     overall: report.overall,
     agents: report.agents,
     components: report.components,
+    componentHealth: report.componentHealth ?? report.components,
     checks: report.checks,
     backups: report.backups,
     nextAction: report.nextAction,

package/src/global/load-component-catalog.js

@@ -1,41 +1,23 @@
 import { readFileSync } from "node:fs";
 import { createManagedSectionBuilder } from "./component-builders.js";
+import { normalizeCatalogDocument } from "./component-manifest.js";
 
 const defaultCatalogUrl = new URL("../../global-template/components/catalog.json", import.meta.url);
 
-function validateCatalogEntry(entry) {
-  const required = ["id", "label", "version", "defaultEnabled", "assetFiles"];
-
-  for (const field of required) {
-    if (entry[field] === undefined) {
-      throw new Error(`Component catalog entry is missing "${field}".`);
-    }
-  }
-
-  if (!Array.isArray(entry.assetFiles) || entry.assetFiles.length === 0) {
-    throw new Error(`Component "${entry.id}" must declare at least one asset file.`);
-  }
-}
-
 export function readComponentCatalogDocument(catalogUrl = defaultCatalogUrl) {
   return JSON.parse(readFileSync(catalogUrl, "utf8"));
 }
 
 export function loadComponentCatalog(catalogUrl = defaultCatalogUrl) {
   const catalog = readComponentCatalogDocument(catalogUrl);
-
-  return catalog.components.map((entry) => {
-    validateCatalogEntry(entry);
-
-    return {
-      id: entry.id,
-      label: entry.label,
-      version: entry.version,
-      source: "bundled",
-      defaultEnabled: entry.defaultEnabled,
-      assetFiles: [...entry.assetFiles],
-      adapterHints: { ...(entry.adapterHints ?? {}) },
-      buildManagedSection: createManagedSectionBuilder(entry.id, entry)
-    };
+  const { components } = normalizeCatalogDocument(catalog, {
+    source: "bundled",
+    requireDefaultEnabled: true
   });
+
+  return components.map((entry) => ({
+    ...entry,
+    source: "bundled",
+    buildManagedSection: createManagedSectionBuilder(entry.id, entry)
+  }));
 }

package/src/global/load-workspace-component-catalog.js

@@ -1,6 +1,7 @@
 import { existsSync, lstatSync, readFileSync, realpathSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { createWorkspaceManagedSectionBuilder } from "./component-builders.js";
+import { normalizeCatalogDocument } from "./component-manifest.js";
 import { isPathInside } from "./component-paths.js";
 
 export function workspaceCatalogPath(workspaceRoot) {
@@ -24,77 +25,35 @@ export function loadWorkspaceComponentCatalog(workspaceRoot, { bundledIds = [] }
   const resolvedRoot = resolve(workspaceRoot);
   const catalog = readWorkspaceCatalogDocument(resolvedRoot);
   const componentsRoot = join(resolvedRoot, ".harness", "components");
-  const entries = catalog.components;
-
-  if (!Array.isArray(entries)) {
-    throw new Error("Workspace component catalog must declare a components array.");
-  }
-
-  const seen = new Set();
-  const components = [];
-
-  for (const entry of entries) {
-    validateWorkspaceEntry(entry, { componentsRoot, workspaceRoot: resolvedRoot, bundledIds, seen });
-    seen.add(entry.id);
+  const { components: entries } = normalizeCatalogDocument(catalog, {
+    source: "workspace",
+    bundledIds,
+    requireDefaultEnabled: false
+  });
+
+  return entries.map((entry) => {
+    const componentDir = join(componentsRoot, entry.id);
+
+    for (const assetFile of entry.assetFiles) {
+      validateAssetPresence(assetFile, {
+        componentDir,
+        componentId: entry.id,
+        workspaceRoot: resolvedRoot
+      });
+    }
 
-    components.push({
-      id: entry.id,
-      label: entry.label,
-      version: entry.version,
+    return {
+      ...entry,
       source: "workspace",
       defaultEnabled: false,
-      assetFiles: [...entry.assetFiles],
-      adapterHints: { ...(entry.adapterHints ?? {}) },
       instructions: entry.instructions ?? null,
       workspaceRoot: resolvedRoot,
       buildManagedSection: createWorkspaceManagedSectionBuilder(entry)
-    });
-  }
-
-  return components;
-}
-
-function validateWorkspaceEntry(entry, { componentsRoot, workspaceRoot, bundledIds, seen }) {
-  const required = ["id", "label", "version", "assetFiles"];
-
-  for (const field of required) {
-    if (entry[field] === undefined) {
-      throw new Error(`Workspace component catalog entry is missing "${field}".`);
-    }
-  }
-
-  if (!Array.isArray(entry.assetFiles) || entry.assetFiles.length === 0) {
-    throw new Error(`Workspace component "${entry.id}" must declare at least one asset file.`);
-  }
-
-  if (bundledIds.includes(entry.id)) {
-    throw new Error(`Workspace component "${entry.id}" conflicts with a bundled component.`);
-  }
-
-  if (seen.has(entry.id)) {
-    throw new Error(`Duplicate workspace component id "${entry.id}".`);
-  }
-
-  const componentDir = join(componentsRoot, entry.id);
-
-  for (const assetFile of entry.assetFiles) {
-    validateAssetFile(assetFile, { componentDir, componentId: entry.id, workspaceRoot });
-  }
+    };
+  });
 }
 
-function validateAssetFile(assetFile, { componentDir, componentId, workspaceRoot }) {
-  if (typeof assetFile !== "string" || assetFile.length === 0) {
-    throw new Error(`Workspace component "${componentId}" has an invalid asset path.`);
-  }
-
-  if (assetFile.startsWith("/") || assetFile.includes("\\") || assetFile.includes("..")) {
-    throw new Error(`Workspace component "${componentId}" asset "${assetFile}" must be a relative path without "..".`);
-  }
-
-  if (assetFile.endsWith("/")) {
-    throw new Error(`Workspace component "${componentId}" asset "${assetFile}" must reference a file.`);
-  }
-
+function validateAssetPresence(assetFile, { componentDir, componentId, workspaceRoot }) {
   const assetPath = join(componentDir, ...assetFile.split("/"));
   const normalized = resolve(assetPath);
 

package/src/global/state-migration.js

@@ -1,5 +1,9 @@
 import { resolveAdapter } from "./registry.js";
 import { resolveComponent } from "./component-registry.js";
+import { normalizeSddState } from "./integrations/sdd-state.js";
+
+export const STATE_VERSION = 4;
+export const UNSUPPORTED_STATE_VERSION = "UNSUPPORTED_STATE_VERSION";
 
 const LEGACY_ORCHESTRATOR_COMPONENT = {
   id: "orchestrator",
@@ -7,17 +11,33 @@ const LEGACY_ORCHESTRATOR_COMPONENT = {
   managedTargets: []
 };
 
+/** Fail closed on future state versions — never silently downgrade. */
+export function assertCompatibleStateVersion(state) {
+  const version = state?.stateVersion;
+  if (typeof version === "number" && version > STATE_VERSION) {
+    const error = new Error(
+      `Unsupported stateVersion ${version}; this runtime supports up to ${STATE_VERSION}.`
+    );
+    error.code = UNSUPPORTED_STATE_VERSION;
+    throw error;
+  }
+}
+
+/** Normalize any compatible v3/v4 (or legacy) state into explicit stateVersion 4. Idempotent for v4. */
 export function normalizeGlobalState(state) {
   if (!state) return null;
+  assertCompatibleStateVersion(state);
 
   const adapters = state.adapters ?? migrateLegacyAgents(state.agents ?? []);
   const components = state.components ?? migrateLegacyComponents(state, adapters);
 
   return {
     ...state,
+    stateVersion: STATE_VERSION,
     adapters,
     agents: toLegacyAgents(adapters),
-    components
+    components,
+    sdd: normalizeSddState(state.sdd)
   };
 }
 

package/src/global/state.js

@@ -1,9 +1,10 @@
 import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
-import { normalizeGlobalState } from "./state-migration.js";
+import { normalizeGlobalState, STATE_VERSION, UNSUPPORTED_STATE_VERSION } from "./state-migration.js";
+import { normalizeSddState } from "./integrations/sdd-state.js";
 
-export const STATE_VERSION = 3;
+export { STATE_VERSION, UNSUPPORTED_STATE_VERSION };
 
 export async function readGlobalState(statePath) {
   if (!existsSync(statePath)) return null;
@@ -11,14 +12,16 @@ export async function readGlobalState(statePath) {
   try {
     const raw = JSON.parse(await readFile(statePath, "utf8"));
     return normalizeGlobalState(raw);
-  } catch {
+  } catch (error) {
+    if (error?.code === UNSUPPORTED_STATE_VERSION) throw error;
     return null;
   }
 }
 
 export async function writeGlobalState(statePath, state) {
+  const normalized = normalizeGlobalState(state) ?? state;
   await mkdir(dirname(statePath), { recursive: true });
-  await writeFile(statePath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+  await writeFile(statePath, `${JSON.stringify(normalized, null, 2)}\n`, "utf8");
 }
 
 export function createGlobalState({
@@ -28,13 +31,14 @@ export function createGlobalState({
   components = [],
   coreFiles,
   backups,
-  installedAt
+  installedAt,
+  sdd
 }) {
   const now = new Date().toISOString();
   const normalizedAdapters = adapters.map((entry) => ({ ...entry }));
   const normalizedComponents = components.map((entry) => ({ ...entry }));
 
-  return {
+  return normalizeGlobalState({
     stateVersion: STATE_VERSION,
     packageName,
     cliVersion,
@@ -45,6 +49,7 @@ export function createGlobalState({
     agents: normalizedAdapters.map(({ id, configFile, present }) => ({ id, configFile, present })),
     components: normalizedComponents,
     coreFiles,
-    backups
-  };
+    backups,
+    sdd: normalizeSddState(sdd)
+  });
 }

package/src/global/status.js

@@ -1,4 +1,5 @@
 import { listBackupSnapshots } from "./backups.js";
+import { buildComponentHealthEntries } from "./component-health.js";
 import { runGlobalDoctorChecks } from "./global-doctor.js";
 import { buildEffectivePolicy } from "./policy.js";
 import { harnessHomePaths } from "./paths.js";
@@ -20,16 +21,8 @@ export async function buildStatusReport(homeDir, { packageRoot, workspaceRoot =
     managed: installedAgentIds.has(id)
   }));
 
-  const components = (state?.components ?? []).map((entry) => {
-    const related = doctor.checks.filter((check) => check.componentId === entry.id);
-    const status = summarizeCheckStatuses(related);
-    return {
-      id: entry.id,
-      version: entry.version,
-      source: entry.source ?? "bundled",
-      status
-    };
-  });
+  const components = buildComponentHealthEntries(state?.components ?? [], doctor.checks)
+    .map(({ checks, ...entry }) => entry);
 
   const counts = {
     ok: doctor.checks.filter((check) => check.status === "ok").length,
@@ -48,6 +41,7 @@ export async function buildStatusReport(homeDir, { packageRoot, workspaceRoot =
     state,
     agents,
     components,
+    componentHealth: doctor.componentHealth,
     checks: doctor.checks,
     backups: backups.length,
     counts,
@@ -58,13 +52,6 @@ export async function buildStatusReport(homeDir, { packageRoot, workspaceRoot =
   };
 }
 
-function summarizeCheckStatuses(checks) {
-  if (checks.length === 0) return "ok";
-  if (checks.some((check) => check.status === "missing")) return "missing";
-  if (checks.some((check) => check.status === "stale")) return "stale";
-  return "ok";
-}
-
 function resolveOverallStatus({ state, doctor }) {
   if (!state) return "missing";
   if (doctor.hasDrift) return "drift";

package/src/global/sync.js

@@ -6,6 +6,7 @@ import {
   shouldPromptApplyConfirmation
 } from "./apply-confirmation.js";
 import { buildDiffReport } from "./diff.js";
+import { needsManagedRepair } from "./governance-repair.js";
 import { harnessHomePaths } from "./paths.js";
 import { printManagedPreflight, shouldShowPreflight, summarizeDiffPreflight } from "./preflight.js";
 import { loadConsentAudit } from "./policy.js";
@@ -42,11 +43,7 @@ export async function runHarnessSync({
   }
 
   const preReport = await buildStatusReport(homeDir, { packageRoot, workspaceRoot });
-  const needsRepair = preReport.overall === "drift"
-    || preReport.counts.missing > 0
-    || preReport.counts.stale > 0;
-
-  if (!needsRepair) {
+  if (!needsManagedRepair(preReport)) {
     return {
       action: "noop",
       wrote: false,