@kal-elsam/kairo-runtime 0.7.0 → 0.9.0

package/src/global/runtime/orchestration/orch-types.js

@@ -0,0 +1,173 @@
+import { createHash, randomBytes } from "node:crypto";
+export const RUN_STRATEGIES = Object.freeze({ DIRECT: "direct", ORCHESTRATED: "orchestrated" });
+export const DAG_NODE_STATES = Object.freeze({
+  PENDING: "pending", READY: "ready", RUNNING: "running", COMPACTING: "compacting",
+  COMPLETED: "completed", FAILED: "failed", CANCELLED: "cancelled", BLOCKED: "blocked"
+});
+export const DAG_TERMINAL_STATES = new Set([
+  DAG_NODE_STATES.COMPLETED, DAG_NODE_STATES.FAILED, DAG_NODE_STATES.CANCELLED
+]);
+export const ORCH_LIMITS = Object.freeze({
+  MAX_DEPTH: 1, DEFAULT_CONCURRENCY: 2, MAX_ATTEMPTS: 2, COMPACT_RATIO: 0.7, STOP_RATIO: 0.9
+});
+export const ORCH_ERROR_CODES = Object.freeze({
+  INVALID_STRATEGY: "invalid_strategy", INVALID_DEPTH: "invalid_depth",
+  INVALID_LINEAGE: "invalid_lineage", INVALID_HANDOFF: "invalid_handoff",
+  INVALID_NODE: "invalid_node", LIMIT_EXCEEDED: "limit_exceeded",
+  FORBIDDEN_FIELD: "forbidden_field", RECEIPT_EXISTS: "receipt_exists"
+});
+export class OrchContractError extends Error {
+  constructor(message, { code, details = null } = {}) {
+    super(message);
+    this.name = "OrchContractError";
+    this.code = code;
+    this.details = details;
+  }
+}
+export function createTaskId() {
+  return `task_${randomBytes(8).toString("hex")}`;
+}
+export function isTerminalDagState(state) {
+  return DAG_TERMINAL_STATES.has(state);
+}
+
+function assertDepth(depth) {
+  const d = Number(depth);
+  if (!Number.isInteger(d) || d < 0) {
+    throw new OrchContractError(`Invalid depth "${depth}".`, {
+      code: ORCH_ERROR_CODES.INVALID_DEPTH, details: { depth }
+    });
+  }
+  if (d > ORCH_LIMITS.MAX_DEPTH) {
+    throw new OrchContractError(`Orchestration depth ${d} exceeds max ${ORCH_LIMITS.MAX_DEPTH}.`, {
+      code: ORCH_ERROR_CODES.INVALID_DEPTH, details: { depth: d }
+    });
+  }
+  return d;
+}
+
+function assertParentForDepth(depth, parentId, { rootMsg, minionMsg, code }) {
+  if (depth === 0 && parentId != null) {
+    throw new OrchContractError(rootMsg, { code });
+  }
+  if (depth > 0 && !parentId) {
+    throw new OrchContractError(minionMsg, { code });
+  }
+}
+
+export function normalizeRunStrategy(value = RUN_STRATEGIES.DIRECT) {
+  const strategy = String(value ?? RUN_STRATEGIES.DIRECT).trim().toLowerCase();
+  if (!Object.values(RUN_STRATEGIES).includes(strategy)) {
+    throw new OrchContractError(`Invalid run strategy "${value}". Use direct or orchestrated.`, {
+      code: ORCH_ERROR_CODES.INVALID_STRATEGY, details: { value }
+    });
+  }
+  return strategy;
+}
+
+/** Lineage: max depth 1 (root=0, minion=1). */
+export function createOrchLineage({ rootRunId, parentRunId = null, taskId = null, depth = 0 } = {}) {
+  if (typeof rootRunId !== "string" || !rootRunId) {
+    throw new OrchContractError("rootRunId is required.", { code: ORCH_ERROR_CODES.INVALID_LINEAGE });
+  }
+  const d = assertDepth(depth);
+  assertParentForDepth(d, parentRunId, {
+    rootMsg: "Root nodes must not set parentRunId.",
+    minionMsg: "Minion nodes require parentRunId.",
+    code: ORCH_ERROR_CODES.INVALID_LINEAGE
+  });
+  return { rootRunId, parentRunId: parentRunId ?? null, taskId: taskId ?? createTaskId(), depth: d };
+}
+
+export function createBudgetUsage({
+  contextTokens = 0, contextLimit = 0,
+  compactRatio = ORCH_LIMITS.COMPACT_RATIO, stopRatio = ORCH_LIMITS.STOP_RATIO
+} = {}) {
+  const tokens = Math.max(0, Number(contextTokens) || 0);
+  const limit = Math.max(0, Number(contextLimit) || 0);
+  const ratio = limit > 0 ? tokens / limit : 0;
+  return {
+    contextTokens: tokens, contextLimit: limit, ratio,
+    shouldCompact: limit > 0 && ratio >= compactRatio && ratio < stopRatio,
+    shouldStop: limit > 0 && ratio >= stopRatio
+  };
+}
+
+export function createDagNode({
+  taskId = null, runId = null, parentTaskId = null, depth = 0,
+  state = DAG_NODE_STATES.PENDING, dependsOn = [], attempt = 0,
+  objectiveDigest = null, budget = null, resultDigest = null, error = null
+} = {}) {
+  if (!Object.values(DAG_NODE_STATES).includes(state)) {
+    throw new OrchContractError(`Invalid DAG node state "${state}".`, {
+      code: ORCH_ERROR_CODES.INVALID_NODE, details: { state }
+    });
+  }
+  const d = assertDepth(depth);
+  assertParentForDepth(d, parentTaskId, {
+    rootMsg: "Root nodes must not set parentTaskId.",
+    minionMsg: "Minion nodes require parentTaskId.",
+    code: ORCH_ERROR_CODES.INVALID_NODE
+  });
+  const attempts = Number(attempt) || 0;
+  if (attempts < 0 || attempts > ORCH_LIMITS.MAX_ATTEMPTS) {
+    throw new OrchContractError(`Attempt ${attempts} outside 0..${ORCH_LIMITS.MAX_ATTEMPTS}.`, {
+      code: ORCH_ERROR_CODES.LIMIT_EXCEEDED, details: { attempt: attempts }
+    });
+  }
+  const deps = [...new Set((dependsOn ?? []).map((id) => {
+    if (typeof id !== "string" || !id) {
+      throw new OrchContractError("Dependency taskId is required.", { code: ORCH_ERROR_CODES.INVALID_NODE });
+    }
+    return id;
+  }))];
+  return {
+    taskId: taskId ?? createTaskId(), runId: runId ?? null, parentTaskId: parentTaskId ?? null,
+    depth: d, state, dependsOn: deps, attempt: attempts,
+    objectiveDigest, budget: budget ?? null, resultDigest, error: error ?? null
+  };
+}
+
+export function createMinionBrief({
+  objective, constraints = [], admittedPaths = [], exitCriteria = [],
+  parentTaskId = null, taskId = null
+} = {}) {
+  if (typeof objective !== "string" || !objective.trim()) {
+    throw new OrchContractError("Minion brief requires a non-empty objective.", {
+      code: ORCH_ERROR_CODES.INVALID_HANDOFF
+    });
+  }
+  return {
+    taskId: taskId ?? createTaskId(), parentTaskId: parentTaskId ?? null,
+    objective: objective.trim(), constraints: (constraints ?? []).map(String),
+    admittedPaths: (admittedPaths ?? []).map(String), exitCriteria: (exitCriteria ?? []).map(String)
+  };
+}
+
+export function createMinionResult({
+  taskId = null, summary, decisions = [], files = [], risks = [],
+  evidence = [], usage = null, compact = false
+} = {}) {
+  if (typeof taskId !== "string" || !taskId) {
+    throw new OrchContractError("Minion result requires taskId.", { code: ORCH_ERROR_CODES.INVALID_HANDOFF });
+  }
+  if (typeof summary !== "string" || !summary.trim()) {
+    throw new OrchContractError("Minion result requires a non-empty summary.", {
+      code: ORCH_ERROR_CODES.INVALID_HANDOFF
+    });
+  }
+  return {
+    taskId, summary: summary.trim(),
+    decisions: (decisions ?? []).map(String), files: (files ?? []).map(String),
+    risks: (risks ?? []).map(String), evidence: (evidence ?? []).map(String),
+    usage: {
+      inputTokens: usage?.inputTokens ?? null, outputTokens: usage?.outputTokens ?? null,
+      totalTokens: usage?.totalTokens ?? null, cost: usage?.cost ?? null
+    },
+    compact: Boolean(compact)
+  };
+}
+
+export function digestAllowlisted(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 16);
+}

package/src/global/runtime/orchestration/orch-validate.js

@@ -0,0 +1,63 @@
+import {
+  ORCH_ERROR_CODES, OrchContractError, createBudgetUsage, createDagNode,
+  createMinionResult, createOrchLineage, normalizeRunStrategy
+} from "./orch-types.js";
+export const FORBIDDEN_KEYS = new Set([
+  "prompt", "diff", "transcript", "raw", "rawOutput", "stdout", "stderr", "output",
+  "message", "messages", "content", "secret", "secrets", "token", "apiKey",
+  "conversation", "history", "toolArgs", "arguments", "objective"
+]);
+export function walkForbiddenKeys(value, path = "") {
+  if (!value || typeof value !== "object") return;
+  if (Array.isArray(value)) {
+    value.forEach((item, i) => walkForbiddenKeys(item, `${path}[${i}]`));
+    return;
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_KEYS.has(key)) {
+      throw new OrchContractError(`Forbidden field "${path}${key}" in orchestration receipt.`, {
+        code: ORCH_ERROR_CODES.FORBIDDEN_FIELD, details: { key, path }
+      });
+    }
+    walkForbiddenKeys(child, `${path}${key}.`);
+  }
+}
+export function assertOrchReceiptSecretFree(receipt) {
+  if (!receipt || typeof receipt !== "object" || Array.isArray(receipt)) {
+    throw new OrchContractError("Invalid orchestration receipt: expected object.", {
+      code: ORCH_ERROR_CODES.FORBIDDEN_FIELD
+    });
+  }
+  walkForbiddenKeys(receipt);
+  if (receipt.version !== 1) {
+    throw new OrchContractError("Orchestration receipt version must be 1.", {
+      code: ORCH_ERROR_CODES.FORBIDDEN_FIELD
+    });
+  }
+  normalizeRunStrategy(receipt.strategy);
+  if (typeof receipt.rootRunId !== "string" || !receipt.rootRunId) {
+    throw new OrchContractError("rootRunId is required on receipt.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  createOrchLineage(receipt.lineage);
+  if (receipt.lineage.rootRunId !== receipt.rootRunId) {
+    throw new OrchContractError("lineage.rootRunId must match receipt.rootRunId.", {
+      code: ORCH_ERROR_CODES.INVALID_LINEAGE
+    });
+  }
+  if (!Array.isArray(receipt.nodes) || !Array.isArray(receipt.results)) {
+    throw new OrchContractError("Receipt requires nodes[] and results[].", {
+      code: ORCH_ERROR_CODES.INVALID_NODE
+    });
+  }
+  for (const node of receipt.nodes) {
+    createDagNode(node);
+    if (node.budget) createBudgetUsage(node.budget);
+  }
+  for (const result of receipt.results) createMinionResult(result);
+  if (typeof receipt.createdAt !== "string" || !receipt.createdAt) {
+    throw new OrchContractError("createdAt is required.", { code: ORCH_ERROR_CODES.FORBIDDEN_FIELD });
+  }
+  return receipt;
+}

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,