@kal-elsam/kairo-runtime 0.7.0 → 0.8.0

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,