@kal-elsam/kairo-runtime 0.6.0 → 0.8.0

package/src/global/runtime/review/review-validate.js

@@ -0,0 +1,280 @@
+import {
+  REVIEW_SEVERITIES,
+  ReviewSnapshotError,
+  assertReviewPathSafe,
+  createFindingId
+} from "./review-types.js";
+
+export const REVIEW_VALIDATION_ERROR_CODES = Object.freeze({
+  INVALID_OUTPUT: "invalid_output",
+  INVALID_FINDING: "invalid_finding",
+  PATH_OUT_OF_SCOPE: "path_out_of_scope",
+  FORBIDDEN_FIELD: "forbidden_field",
+  RECEIPT_EXISTS: "receipt_exists"
+});
+
+const SEVERITY_SET = new Set(Object.values(REVIEW_SEVERITIES));
+const FORBIDDEN_KEYS = new Set([
+  "prompt", "diff", "transcript", "raw", "rawOutput", "stdout", "stderr",
+  "output", "message", "messages", "content", "secret", "secrets", "token", "apiKey"
+]);
+
+const RECEIPT_SHAPE = Object.freeze({
+  version: "number",
+  reviewId: "string",
+  agentId: "string",
+  model: "string?",
+  state: "string",
+  snapshot: {
+    mode: "string",
+    headSha: "string",
+    base: "string?",
+    commit: "string?",
+    fingerprint: "string",
+    totals: { fileCount: "number", changedLines: "number", diffBytes: "number" },
+    files: [{ path: "string", sourcePath: "string?", status: "string", hash: "string", changedLines: "number" }],
+    excluded: [{ path: "string", reason: "string" }]
+  },
+  findings: [{
+    id: "string",
+    severity: "string",
+    title: "string",
+    path: "string",
+    line: "number?",
+    problem: "string",
+    recommendation: "string"
+  }],
+  warnings: ["string"],
+  usage: {
+    inputTokens: "number?",
+    outputTokens: "number?",
+    totalTokens: "number?",
+    cost: "number?"
+  },
+  timings: { startedAt: "string?", finishedAt: "string?", durationMs: "number?" },
+  cliVersion: "string?",
+  createdAt: "string"
+});
+
+export class ReviewValidationError extends Error {
+  constructor(message, { code, details = null } = {}) {
+    super(message);
+    this.name = "ReviewValidationError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function asObject(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ReviewValidationError(`Invalid ${label}: expected object.`, {
+      code: REVIEW_VALIDATION_ERROR_CODES.INVALID_OUTPUT
+    });
+  }
+  return value;
+}
+
+function normalizeLine(line) {
+  if (line == null || line === "") return null;
+  if (!Number.isInteger(line) || line < 1) {
+    throw new ReviewValidationError(`Invalid finding line "${line}".`, {
+      code: REVIEW_VALIDATION_ERROR_CODES.INVALID_FINDING,
+      details: { line }
+    });
+  }
+  return line;
+}
+
+function requireNonEmptyString(value, field) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new ReviewValidationError(`Finding missing ${field}.`, {
+      code: REVIEW_VALIDATION_ERROR_CODES.INVALID_FINDING,
+      details: { field }
+    });
+  }
+  return value.trim();
+}
+
+function isOptionalScalar(spec) {
+  return typeof spec === "string" && spec.endsWith("?");
+}
+
+function scalarType(spec) {
+  return isOptionalScalar(spec) ? spec.slice(0, -1) : spec;
+}
+
+function assertNoForbiddenKeys(value, path) {
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertNoForbiddenKeys(entry, `${path}[${index}]`));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      throw new ReviewValidationError(`Receipt must not include "${key}" at ${path}.`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.FORBIDDEN_FIELD,
+        details: { key, path }
+      });
+    }
+    assertNoForbiddenKeys(child, `${path}.${key}`);
+  }
+}
+
+function assertMatchesShape(value, shape, path) {
+  if (shape === null) {
+    if (value !== null) {
+      throw new ReviewValidationError(`Expected null at ${path}.`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.INVALID_OUTPUT, details: { path }
+      });
+    }
+    return;
+  }
+
+  if (typeof shape === "string") {
+    if (value == null) {
+      if (isOptionalScalar(shape) || shape === "null") return;
+      throw new ReviewValidationError(`Missing value at ${path}.`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.INVALID_OUTPUT, details: { path }
+      });
+    }
+    const expected = scalarType(shape);
+    if (expected === "number" && typeof value === "number" && Number.isFinite(value)) return;
+    if (expected === "string" && typeof value === "string") return;
+    throw new ReviewValidationError(`Invalid type at ${path}.`, {
+      code: REVIEW_VALIDATION_ERROR_CODES.INVALID_OUTPUT, details: { path, expected }
+    });
+  }
+
+  if (Array.isArray(shape)) {
+    if (!Array.isArray(value)) {
+      throw new ReviewValidationError(`Expected array at ${path}.`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.INVALID_OUTPUT, details: { path }
+      });
+    }
+    const itemShape = shape[0];
+    value.forEach((entry, index) => assertMatchesShape(entry, itemShape, `${path}[${index}]`));
+    return;
+  }
+
+  if (value == null) {
+    // Optional object fields (usage/timings) may be null.
+    return;
+  }
+
+  const body = asObject(value, path);
+  const allowed = new Set(Object.keys(shape));
+  for (const key of Object.keys(body)) {
+    if (!allowed.has(key)) {
+      throw new ReviewValidationError(`Unexpected field "${key}" at ${path}.`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.FORBIDDEN_FIELD,
+        details: { key, path }
+      });
+    }
+  }
+  for (const [key, childShape] of Object.entries(shape)) {
+    if (!(key in body)) {
+      throw new ReviewValidationError(`Missing field "${key}" at ${path}.`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.INVALID_OUTPUT, details: { path, key }
+      });
+    }
+    assertMatchesShape(body[key], childShape, `${path}.${key}`);
+  }
+}
+
+/**
+ * Fail-closed parse of agent review JSON against a snapshot scope.
+ * Never accepts paths outside snapshot.files.
+ */
+export function validateReviewOutput(raw, snapshot) {
+  let parsed = raw;
+  if (typeof raw === "string") {
+    try {
+      parsed = JSON.parse(raw);
+    } catch (error) {
+      throw new ReviewValidationError(`Broken review JSON: ${error.message}`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.INVALID_OUTPUT
+      });
+    }
+  }
+
+  const body = asObject(parsed, "review output");
+  assertNoForbiddenKeys(body, "output");
+  const findingsIn = Array.isArray(body.findings) ? body.findings : null;
+  if (!findingsIn) {
+    throw new ReviewValidationError("Review output missing findings array.", {
+      code: REVIEW_VALIDATION_ERROR_CODES.INVALID_OUTPUT
+    });
+  }
+
+  const allowed = new Set((snapshot?.files ?? []).map((f) => f.path));
+  const findings = [];
+
+  for (const entry of findingsIn) {
+    const item = asObject(entry, "finding");
+    assertNoForbiddenKeys(item, "finding");
+    const severity = requireNonEmptyString(item.severity, "severity").toLowerCase();
+    if (!SEVERITY_SET.has(severity)) {
+      throw new ReviewValidationError(`Unknown severity "${item.severity}".`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.INVALID_FINDING,
+        details: { severity: item.severity }
+      });
+    }
+
+    let path;
+    try {
+      path = assertReviewPathSafe(requireNonEmptyString(item.path, "path"));
+    } catch (error) {
+      if (error instanceof ReviewSnapshotError) {
+        throw new ReviewValidationError(error.message, {
+          code: REVIEW_VALIDATION_ERROR_CODES.INVALID_FINDING,
+          details: error.details
+        });
+      }
+      throw error;
+    }
+
+    if (!allowed.has(path)) {
+      throw new ReviewValidationError(`Finding path "${path}" is outside the review snapshot.`, {
+        code: REVIEW_VALIDATION_ERROR_CODES.PATH_OUT_OF_SCOPE,
+        details: { path }
+      });
+    }
+
+    const title = requireNonEmptyString(item.title, "title");
+    const problem = requireNonEmptyString(item.problem, "problem");
+    const recommendation = requireNonEmptyString(item.recommendation, "recommendation");
+    const line = normalizeLine(item.line);
+    const id = createFindingId({ severity, title, path, line, problem });
+    findings.push({ id, severity, title, path, line, problem, recommendation });
+  }
+
+  const warnings = Array.isArray(body.warnings)
+    ? body.warnings.filter((w) => typeof w === "string" && w.trim()).map((w) => w.trim())
+    : [];
+
+  return {
+    findings,
+    warnings,
+    model: typeof body.model === "string" ? body.model : null,
+    usage: sanitizeUsage(body.usage)
+  };
+}
+
+function sanitizeUsage(usage) {
+  if (!usage || typeof usage !== "object" || Array.isArray(usage)) return null;
+  assertNoForbiddenKeys(usage, "usage");
+  return {
+    inputTokens: Number.isFinite(usage.inputTokens) ? usage.inputTokens : null,
+    outputTokens: Number.isFinite(usage.outputTokens) ? usage.outputTokens : null,
+    totalTokens: Number.isFinite(usage.totalTokens) ? usage.totalTokens : null,
+    cost: Number.isFinite(usage.cost) ? usage.cost : null
+  };
+}
+
+/** Recursive forbidden-key + allowlisted shape check before persistence. */
+export function assertReceiptSecretFree(receipt) {
+  const body = asObject(receipt, "receipt");
+  assertNoForbiddenKeys(body, "receipt");
+  assertMatchesShape(body, RECEIPT_SHAPE, "receipt");
+  return body;
+}

package/src/global/runtime/run-cli.js

@@ -45,6 +45,7 @@ export async function runGlobalRun(options, packageManifest, { startRunImpl = st
     captureTranscript,
     cliVersion: packageManifest.version,
     profile: profileResolved,
+    strategy: options.strategy ?? "direct",
     follow: options.follow,
     timeoutMs: options.timeoutMs,
     wait: options.wait !== false

package/src/global/runtime/run-manager.js

@@ -5,6 +5,7 @@ import {
   appendRunEvent,
   appendRunStartedEvent,
   createRunRecord,
+  listRunRecords,
   readRunState,
   reconcileActiveRuns,
   writeRunState
@@ -22,6 +23,20 @@ import {
   readSupervisorLockForRun,
   supervisePreparedRun
 } from "./run-supervisor.js";
+import {
+  assertManagedMinionExtension,
+  assertOrchestratedAgent,
+  createRootRunLineage,
+  normalizeRunStrategy,
+  RUN_STRATEGIES
+} from "./run-strategy.js";
+import {
+  DAG_NODE_STATES,
+  createDagNode,
+  createOrchState,
+  reconcileOrchState,
+  saveOrchState
+} from "./orchestration/index.js";
 
 const activeProcesses = new Map();
 const cancelledRuns = new Set();
@@ -55,6 +70,19 @@ export async function recoverRuns(homeDir) {
     exceptRunIds: listActiveRunIds(),
     isRunAliveImpl: isRunSupervisedAlive
   });
+  for (const run of await listRunRecords(homeDir)) {
+    if (normalizeRunStrategy(run.strategy ?? RUN_STRATEGIES.DIRECT) !== RUN_STRATEGIES.ORCHESTRATED) {
+      continue;
+    }
+    if (await isRunSupervisedAlive(homeDir, run)) {
+      continue;
+    }
+    try {
+      await reconcileOrchState(run.runId, { homeDir });
+    } catch {
+      // Fail closed per root: never invent receipt evidence from corrupt state.
+    }
+  }
   return interrupted;
 }
 
@@ -67,8 +95,10 @@ async function prepareRun({
   permissions = [],
   captureTranscript = false,
   cliVersion,
-  profile = null
+  profile = null,
+  strategy = "direct"
 }) {
+  const normalizedStrategy = assertOrchestratedAgent(agentId, strategy);
   const adapter = resolveExecutionAdapter(agentId);
   const availability = adapter.availability({ cwd });
 
@@ -83,7 +113,12 @@ async function prepareRun({
     );
   }
 
+  if (normalizedStrategy === RUN_STRATEGIES.ORCHESTRATED) {
+    await assertManagedMinionExtension(homeDir);
+  }
+
   const runId = createRunId();
+  const lineage = createRootRunLineage(runId);
   const metadata = createRunMetadata({
     runId,
     agentId,
@@ -94,7 +129,9 @@ async function prepareRun({
     permissions,
     captureTranscript,
     cliVersion,
-    profileSources: profile?.sources ?? null
+    profileSources: profile?.sources ?? null,
+    strategy: normalizedStrategy,
+    lineage
   });
 
   await createRunRecord(homeDir, metadata);
@@ -107,9 +144,25 @@ async function prepareRun({
     permissions,
     captureTranscript,
     cliVersion,
-    profile: profile?.profile ?? null
+    profile: profile?.profile ?? null,
+    strategy: normalizedStrategy
   });
 
+  if (normalizedStrategy === RUN_STRATEGIES.ORCHESTRATED) {
+    await saveOrchState(createOrchState({
+      rootRunId: runId,
+      strategy: normalizedStrategy,
+      lineage,
+      nodes: [createDagNode({
+        taskId: lineage.taskId,
+        runId,
+        depth: 0,
+        state: DAG_NODE_STATES.RUNNING
+      })],
+      cliVersion
+    }), { homeDir });
+  }
+
   return { runId, metadata };
 }
 
@@ -123,6 +176,7 @@ export async function startRun({
   captureTranscript = false,
   cliVersion,
   profile = null,
+  strategy = "direct",
   follow = false,
   timeoutMs = null,
   wait = true,
@@ -138,7 +192,8 @@ export async function startRun({
     permissions,
     captureTranscript,
     cliVersion,
-    profile
+    profile,
+    strategy: normalizeRunStrategy(strategy)
   });
 
   if (!wait) {

package/src/global/runtime/run-strategy.js

@@ -0,0 +1,71 @@
+import { stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  RUN_STRATEGIES,
+  normalizeRunStrategy,
+  createOrchLineage,
+  resolveKairoMinionExtensionPath
+} from "./orchestration/index.js";
+
+export { RUN_STRATEGIES, normalizeRunStrategy };
+
+const ORCH_MODULE_PATH = join(dirname(fileURLToPath(import.meta.url)), "orchestration", "index.js");
+
+export const ORCH_RUNTIME_ENV = Object.freeze({
+  HOME: "KAIRO_ORCH_HOME",
+  ROOT_RUN_ID: "KAIRO_ORCH_ROOT_RUN_ID",
+  ROOT_TASK_ID: "KAIRO_ORCH_ROOT_TASK_ID",
+  CLI_VERSION: "KAIRO_ORCH_CLI_VERSION",
+  MODULE: "KAIRO_ORCH_MODULE"
+});
+
+/** Reject orchestrated for non-Pi before any run I/O. */
+export function assertOrchestratedAgent(agentId, strategy) {
+  const normalized = normalizeRunStrategy(strategy);
+  if (normalized === RUN_STRATEGIES.ORCHESTRATED && agentId !== "pi") {
+    throw new Error(
+      `Strategy "orchestrated" requires agent "pi" (got "${agentId}").`
+    );
+  }
+  return normalized;
+}
+
+/** Fail closed when managed extension is missing or not a regular file. */
+export async function assertManagedMinionExtension(homeDir) {
+  const extensionPath = resolveKairoMinionExtensionPath(homeDir);
+  let info;
+  try {
+    info = await stat(extensionPath);
+  } catch {
+    throw new Error(`Managed Kairo minion extension missing: ${extensionPath}`);
+  }
+  if (!info.isFile()) {
+    throw new Error(`Managed Kairo minion extension is not a regular file: ${extensionPath}`);
+  }
+  return extensionPath;
+}
+
+export function createRootRunLineage(runId) {
+  return createOrchLineage({ rootRunId: runId, parentRunId: null, depth: 0 });
+}
+
+/** Supervisor derives extension path from homeDir only — never from CLI/handoff. */
+export function resolveOrchestratedExtensionPath(homeDir, strategy) {
+  if (normalizeRunStrategy(strategy) !== RUN_STRATEGIES.ORCHESTRATED) return null;
+  return resolveKairoMinionExtensionPath(homeDir);
+}
+
+export function buildOrchestratedRuntimeEnv({
+  homeDir, rootRunId, rootTaskId, cliVersion = null,
+  strategy = RUN_STRATEGIES.DIRECT, baseEnv = process.env
+} = {}) {
+  const env = { ...baseEnv };
+  if (normalizeRunStrategy(strategy) !== RUN_STRATEGIES.ORCHESTRATED) return env;
+  env[ORCH_RUNTIME_ENV.HOME] = homeDir;
+  env[ORCH_RUNTIME_ENV.ROOT_RUN_ID] = rootRunId;
+  env[ORCH_RUNTIME_ENV.ROOT_TASK_ID] = rootTaskId;
+  env[ORCH_RUNTIME_ENV.CLI_VERSION] = cliVersion == null ? "" : String(cliVersion);
+  env[ORCH_RUNTIME_ENV.MODULE] = ORCH_MODULE_PATH;
+  return env;
+}

package/src/global/runtime/run-supervisor.js

@@ -18,6 +18,12 @@ import { consumeRunHandoff } from "./run-handoff.js";
 import { isRunCancelRequested } from "./run-cancel-signal.js";
 import { readSupervisorLock, touchSupervisorLock, writeSupervisorLock } from "./run-supervisor-lock.js";
 import { shouldPersistTranscript } from "./run-redact.js";
+import {
+  buildOrchestratedRuntimeEnv,
+  normalizeRunStrategy,
+  resolveOrchestratedExtensionPath
+} from "./run-strategy.js";
+import { finalizeOrchState, RUN_STRATEGIES } from "./orchestration/index.js";
 
 async function shouldPreserveCancelledState(homeDir, runId) {
   const fresh = await readRunState(homeDir, runId);
@@ -66,12 +72,16 @@ export async function supervisePreparedRun({
   }
 
   const captureTranscript = handoff.captureTranscript === true;
+  const strategy = normalizeRunStrategy(handoff.strategy ?? metadata.strategy ?? "direct");
+  const extensionPath = resolveOrchestratedExtensionPath(homeDir, strategy);
   const launch = adapter.buildLaunch({
     task: handoff.task,
     cwd: handoff.cwd,
     model: handoff.model,
     permissions: handoff.permissions ?? [],
-    profile: handoff.profile ?? null
+    profile: handoff.profile ?? null,
+    strategy,
+    extensionPath
   });
 
   metadata = {
@@ -90,7 +100,14 @@ export async function supervisePreparedRun({
 
   const child = spawnImpl(launch.command, launch.args, {
     cwd: launch.cwd,
-    env: launch.env,
+    env: buildOrchestratedRuntimeEnv({
+      homeDir,
+      rootRunId: runId,
+      rootTaskId: metadata.lineage?.taskId,
+      cliVersion: metadata.cliVersion,
+      strategy,
+      baseEnv: launch.env ?? process.env
+    }),
     stdio: ["ignore", "pipe", "pipe"]
   });
   activeProcesses?.set(runId, child);
@@ -244,6 +261,9 @@ export async function supervisePreparedRun({
             type: failed ? "run.failed" : "run.completed",
             data: { exitCode }
           }), { captureTranscript: shouldPersistTranscript(captureTranscript) });
+          if (!failed && strategy === RUN_STRATEGIES.ORCHESTRATED) {
+            await finalizeOrchState(runId, { homeDir, recovered: false });
+          }
           resolve(metadata);
         });
       } catch (error) {

package/src/global/runtime/run-types.js

@@ -83,7 +83,9 @@ export function createRunMetadata({
   permissions = [],
   captureTranscript = false,
   cliVersion,
-  profileSources = null
+  profileSources = null,
+  strategy = "direct",
+  lineage = null
 }) {
   const { taskDigest, taskLength } = createTaskFingerprint(task);
   const now = new Date().toISOString();
@@ -100,6 +102,8 @@ export function createRunMetadata({
     captureTranscript,
     cliVersion,
     profileSources,
+    strategy,
+    lineage,
     state: RUN_STATES.PENDING,
     pid: null,
     supervisorPid: null,

package/src/global/runtime/write-atomic-json.js

@@ -1,30 +1,36 @@
-import { open as fsOpen, rename as fsRename, unlink as fsUnlink } from "node:fs/promises";
+import {
+  open as fsOpen, rename as fsRename, unlink as fsUnlink, link as fsLink
+} from "node:fs/promises";
 import { constants } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 
 function defaultTempPath(targetPath) {
-  const id = randomBytes(8).toString("hex");
   return join(
     dirname(targetPath),
-    `.${basename(targetPath)}.${process.pid}.${id}.tmp`
+    `.${basename(targetPath)}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`
   );
 }
 
+async function bestEffort(fn) {
+  try { await fn(); } catch { /* ignore */ }
+}
+
 /**
- * Atomically replace targetPath with pretty-printed JSON.
- * Creates a unique temp in the same directory (O_EXCL), writes + fsync,
- * renames over the destination, and deletes the temp on any failure.
+ * Atomic JSON write. Default rename-replace; createExclusive uses link (EEXIST).
+ * link/rename are commit points; post-commit temp cleanup is best-effort.
  */
 export async function writeAtomicJson(targetPath, value, deps = {}) {
   const open = deps.open ?? fsOpen;
   const rename = deps.rename ?? fsRename;
   const unlink = deps.unlink ?? fsUnlink;
+  const link = deps.link ?? fsLink;
   const createTempPath = deps.createTempPath ?? defaultTempPath;
-
+  const createExclusive = deps.createExclusive === true;
   const payload = `${JSON.stringify(value, null, 2)}\n`;
   const tempPath = createTempPath(targetPath);
   let handle;
+  let committed = false;
 
   try {
     handle = await open(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
@@ -32,20 +38,18 @@ export async function writeAtomicJson(targetPath, value, deps = {}) {
     await handle.sync();
     await handle.close();
     handle = undefined;
-    await rename(tempPath, targetPath);
-  } catch (error) {
-    if (handle) {
-      try {
-        await handle.close();
-      } catch {
-        // Best-effort close before temp cleanup.
-      }
-    }
-    try {
-      await unlink(tempPath);
-    } catch {
-      // Temp may not exist yet or already renamed.
+    if (createExclusive) {
+      await link(tempPath, targetPath);
+      committed = true;
+      await bestEffort(() => unlink(tempPath));
+    } else {
+      await rename(tempPath, targetPath);
+      committed = true;
     }
+  } catch (error) {
+    if (committed) return;
+    if (handle) await bestEffort(() => handle.close());
+    await bestEffort(() => unlink(tempPath));
     throw error;
   }
 }