@kal-elsam/kairo-runtime 0.2.1 → 0.2.3

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

@@ -0,0 +1,144 @@
+import { RUN_EVENT_TYPES } from "./run-types.js";
+import { redactObject } from "./run-redact.js";
+
+export function createRunEvent({
+  runId,
+  type,
+  source = "kairo",
+  data = {},
+  captureTranscript = false
+}) {
+  return {
+    timestamp: new Date().toISOString(),
+    runId,
+    type,
+    source,
+    data: sanitizeEventData(data, { captureTranscript })
+  };
+}
+
+export function sanitizeEventData(data, { captureTranscript = false } = {}) {
+  const allowTranscript = captureTranscript === true;
+  return redactObject(data, { allowTranscript });
+}
+
+export function normalizeAdapterEvent(adapterId, raw, { captureTranscript = false } = {}) {
+  if (raw == null) return null;
+
+  if (typeof raw === "object" && raw.type && raw.runId) {
+    return {
+      ...raw,
+      data: sanitizeEventData(raw.data ?? {}, { captureTranscript })
+    };
+  }
+
+  if (typeof raw === "object" && raw.type) {
+    return mapStructuredEvent(adapterId, raw, { captureTranscript });
+  }
+
+  if (typeof raw === "string") {
+    return {
+      timestamp: new Date().toISOString(),
+      type: RUN_EVENT_TYPES.STDOUT,
+      source: adapterId,
+      data: sanitizeEventData({ line: raw }, { captureTranscript })
+    };
+  }
+
+  return null;
+}
+
+function mapStructuredEvent(adapterId, raw, { captureTranscript }) {
+  const base = {
+    timestamp: new Date().toISOString(),
+    source: adapterId,
+    data: sanitizeEventData(extractEventData(raw), { captureTranscript })
+  };
+
+  switch (raw.type) {
+    case "system":
+      return { ...base, type: RUN_EVENT_TYPES.SYSTEM };
+    case "assistant":
+      return { ...base, type: RUN_EVENT_TYPES.ASSISTANT };
+    case "tool_call":
+      return { ...base, type: RUN_EVENT_TYPES.TOOL_CALL };
+    case "tool_result":
+      return { ...base, type: RUN_EVENT_TYPES.TOOL_RESULT };
+    case "result":
+      return { ...base, type: RUN_EVENT_TYPES.RESULT };
+    case "token_usage":
+    case "usage":
+      return { ...base, type: RUN_EVENT_TYPES.TOKEN_USAGE };
+    case "diff":
+    case "diff_summary":
+      return { ...base, type: RUN_EVENT_TYPES.DIFF_SUMMARY };
+    default:
+      return {
+        ...base,
+        type: RUN_EVENT_TYPES.SYSTEM,
+        data: sanitizeEventData({ rawType: raw.type, payload: extractEventData(raw) }, { captureTranscript })
+      };
+  }
+}
+
+function extractEventData(raw) {
+  const { type: _type, ...rest } = raw;
+  return rest;
+}
+
+export function applyEventToMetadata(metadata, event) {
+  const next = { ...metadata, updatedAt: event.timestamp ?? new Date().toISOString() };
+
+  switch (event.type) {
+    case RUN_EVENT_TYPES.TOOL_CALL: {
+      const tool = event.data?.tool_name ?? event.data?.name ?? event.data?.tool ?? event.data?.toolName ?? "unknown";
+      if (!next.tools.includes(tool)) {
+        next.tools = [...next.tools, tool];
+      }
+      break;
+    }
+    case RUN_EVENT_TYPES.STDERR:
+    case RUN_EVENT_TYPES.STDOUT: {
+      const command = event.data?.command;
+      if (command && !next.commands.includes(command)) {
+        next.commands = [...next.commands, command];
+      }
+      break;
+    }
+    case RUN_EVENT_TYPES.TOKEN_USAGE: {
+      next.tokenUsage = {
+        input: event.data?.inputTokens ?? event.data?.input ?? next.tokenUsage?.input ?? null,
+        output: event.data?.outputTokens ?? event.data?.output ?? next.tokenUsage?.output ?? null,
+        total: event.data?.totalTokens ?? event.data?.total ?? next.tokenUsage?.total ?? null
+      };
+      if (event.data?.cost != null) {
+        next.cost = event.data.cost;
+      }
+      break;
+    }
+    case RUN_EVENT_TYPES.DIFF_SUMMARY: {
+      next.diffSummary = {
+        filesChanged: event.data?.filesChanged ?? event.data?.files ?? null,
+        insertions: event.data?.insertions ?? null,
+        deletions: event.data?.deletions ?? null
+      };
+      break;
+    }
+    default:
+      break;
+  }
+
+  return next;
+}
+
+export function transitionRunState(metadata, nextState, { exitCode = null, error = null } = {}) {
+  const now = new Date().toISOString();
+  return {
+    ...metadata,
+    state: nextState,
+    exitCode: exitCode ?? metadata.exitCode,
+    error: error ?? metadata.error,
+    updatedAt: now,
+    completedAt: now
+  };
+}

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

@@ -0,0 +1,71 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { runPaths } from "../paths.js";
+import { getRunsDir, readRunState } from "./run-store.js";
+import { isActiveRunState } from "./run-types.js";
+import { isWithinStartingGrace } from "./run-starting.js";
+import { readSupervisorLock } from "./run-supervisor-lock.js";
+
+function handoffPath(homeDir, runId) {
+  return `${runPaths(homeDir, runId).runDir}/handoff.json`;
+}
+
+export async function writeRunHandoff(homeDir, runId, payload) {
+  const { runDir } = runPaths(homeDir, runId);
+  await mkdir(runDir, { recursive: true });
+  await writeFile(handoffPath(homeDir, runId), `${JSON.stringify(payload)}\n`, "utf8");
+}
+
+export async function consumeRunHandoff(homeDir, runId) {
+  const path = handoffPath(homeDir, runId);
+  if (!existsSync(path)) {
+    throw new Error(`Missing run handoff for "${runId}".`);
+  }
+
+  const payload = JSON.parse(await readFile(path, "utf8"));
+  await rm(path, { force: true });
+  return payload;
+}
+
+export async function deleteRunHandoff(homeDir, runId) {
+  await rm(handoffPath(homeDir, runId), { force: true });
+}
+
+export function hasRunHandoff(homeDir, runId) {
+  return existsSync(handoffPath(homeDir, runId));
+}
+
+export async function cleanupStaleHandoffs(homeDir, { exceptRunIds = [], isRunAliveImpl } = {}) {
+  const except = new Set(exceptRunIds);
+  const runsDir = getRunsDir(homeDir);
+  if (!existsSync(runsDir)) return [];
+
+  const cleaned = [];
+  const entries = await readdir(runsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const runId = entry.name;
+    if (except.has(runId)) continue;
+    if (!hasRunHandoff(homeDir, runId)) continue;
+
+    const state = await readRunState(homeDir, runId);
+    const lock = await readSupervisorLock(homeDir, runId);
+
+    if (isWithinStartingGrace(state, lock)) {
+      continue;
+    }
+
+    if (isRunAliveImpl && state && await isRunAliveImpl(homeDir, state)) {
+      continue;
+    }
+
+    if (!state || !isActiveRunState(state.state)) {
+      await deleteRunHandoff(homeDir, runId);
+      cleaned.push(runId);
+    }
+  }
+
+  return cleaned;
+}

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

@@ -0,0 +1,28 @@
+export function isProcessAlive(pid) {
+  if (pid == null || pid <= 0) return false;
+
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && typeof error === "object" && error.code === "EPERM";
+  }
+}
+
+export async function isRunAlive(homeDir, run, { readSupervisorLockImpl } = {}) {
+  if (run.pid && isProcessAlive(run.pid)) {
+    return true;
+  }
+
+  if (readSupervisorLockImpl) {
+    const lock = await readSupervisorLockImpl(homeDir, run.runId);
+    if (lock?.agentPid && isProcessAlive(lock.agentPid)) {
+      return true;
+    }
+    if (lock?.supervisorPid && isProcessAlive(lock.supervisorPid)) {
+      return true;
+    }
+  }
+
+  return false;
+}

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

@@ -0,0 +1,271 @@
+import { spawn } from "node:child_process";
+import { createRunId, createRunMetadata, RUN_STATES } from "./run-types.js";
+import { createRunEvent, transitionRunState } from "./run-events.js";
+import {
+  appendRunEvent,
+  appendRunStartedEvent,
+  createRunRecord,
+  readRunState,
+  reconcileActiveRuns,
+  writeRunState
+} from "./run-store.js";
+import { resolveExecutionAdapter } from "./execution-adapters/index.js";
+import { resolveProfileAgents } from "../profile.js";
+import { resolveRuntimeOptions } from "./run-profile.js";
+import { cleanupStaleHandoffs, deleteRunHandoff, writeRunHandoff } from "./run-handoff.js";
+import { isRunAlive } from "./run-liveness.js";
+import { readSupervisorLock, writeSupervisorLock } from "./run-supervisor-lock.js";
+import { writeCancelSignal } from "./run-cancel-signal.js";
+import { isWithinStartingGrace } from "./run-starting.js";
+import {
+  forkDetachedSupervisor,
+  readSupervisorLockForRun,
+  supervisePreparedRun
+} from "./run-supervisor.js";
+
+const activeProcesses = new Map();
+const cancelledRuns = new Set();
+
+export function getActiveProcess(runId) {
+  return activeProcesses.get(runId) ?? null;
+}
+
+export function listActiveRunIds() {
+  return [...activeProcesses.keys()];
+}
+
+async function isRunSupervisedAlive(homeDir, run) {
+  if (listActiveRunIds().includes(run.runId)) {
+    return true;
+  }
+
+  const lock = await readSupervisorLock(homeDir, run.runId);
+  if (isWithinStartingGrace(run, lock)) {
+    return true;
+  }
+
+  return isRunAlive(homeDir, run, { readSupervisorLockImpl: readSupervisorLockForRun });
+}
+
+export async function recoverRuns(homeDir) {
+  const interrupted = await reconcileActiveRuns(homeDir, {
+    isRunAliveImpl: isRunSupervisedAlive
+  });
+  await cleanupStaleHandoffs(homeDir, {
+    exceptRunIds: listActiveRunIds(),
+    isRunAliveImpl: isRunSupervisedAlive
+  });
+  return interrupted;
+}
+
+async function prepareRun({
+  homeDir,
+  agentId,
+  task,
+  cwd,
+  model = null,
+  permissions = [],
+  captureTranscript = false,
+  cliVersion,
+  profile = null
+}) {
+  const adapter = resolveExecutionAdapter(agentId);
+  const availability = adapter.availability({ cwd });
+
+  if (!availability.available) {
+    throw new Error(availability.reason ?? `${adapter.label} is not available.`);
+  }
+
+  if (!availability.launchable) {
+    throw new Error(
+      availability.reason
+        ?? `${adapter.label} is not launchable for auditable Kairo runs in v1.`
+    );
+  }
+
+  const runId = createRunId();
+  const metadata = createRunMetadata({
+    runId,
+    agentId,
+    provider: adapter.label,
+    model,
+    task,
+    cwd,
+    permissions,
+    captureTranscript,
+    cliVersion,
+    profileSources: profile?.sources ?? null
+  });
+
+  await createRunRecord(homeDir, metadata);
+  await appendRunStartedEvent(homeDir, metadata);
+  await writeRunHandoff(homeDir, runId, {
+    agentId,
+    task,
+    cwd,
+    model,
+    permissions,
+    captureTranscript,
+    cliVersion,
+    profile: profile?.profile ?? null
+  });
+
+  return { runId, metadata };
+}
+
+export async function startRun({
+  homeDir,
+  agentId,
+  task,
+  cwd,
+  model = null,
+  permissions = [],
+  captureTranscript = false,
+  cliVersion,
+  profile = null,
+  follow = false,
+  timeoutMs = null,
+  wait = true,
+  spawnImpl = spawn,
+  forkDetachedSupervisorImpl = forkDetachedSupervisor
+}) {
+  const { runId, metadata } = await prepareRun({
+    homeDir,
+    agentId,
+    task,
+    cwd,
+    model,
+    permissions,
+    captureTranscript,
+    cliVersion,
+    profile
+  });
+
+  if (!wait) {
+    const startingAt = new Date().toISOString();
+    await writeRunState(homeDir, {
+      ...metadata,
+      state: RUN_STATES.STARTING,
+      updatedAt: startingAt
+    });
+    await writeSupervisorLock(homeDir, runId, {
+      startingAt,
+      supervisorPid: null,
+      agentPid: null,
+      lastHeartbeat: startingAt
+    });
+
+    let supervisorPid;
+    try {
+      supervisorPid = forkDetachedSupervisorImpl({ homeDir, runId });
+      if (!supervisorPid) {
+        throw new Error("Failed to start detached supervisor.");
+      }
+      await writeSupervisorLock(homeDir, runId, {
+        startingAt,
+        supervisorPid,
+        agentPid: null,
+        startedAt: startingAt,
+        lastHeartbeat: startingAt
+      });
+    } catch (error) {
+      await deleteRunHandoff(homeDir, runId);
+      const failed = transitionRunState(
+        { ...metadata, state: RUN_STATES.STARTING },
+        RUN_STATES.FAILED,
+        { error: error instanceof Error ? error.message : String(error) }
+      );
+      await writeRunState(homeDir, failed);
+      throw error;
+    }
+
+    const detachedMetadata = {
+      ...metadata,
+      state: RUN_STATES.STARTING,
+      supervisorPid,
+      updatedAt: startingAt
+    };
+    await writeRunState(homeDir, detachedMetadata);
+    return {
+      runId,
+      metadata: detachedMetadata,
+      completion: null
+    };
+  }
+
+  const completion = supervisePreparedRun({
+    homeDir,
+    runId,
+    follow,
+    timeoutMs,
+    spawnImpl,
+    cancelledRuns,
+    activeProcesses
+  });
+
+  return {
+    runId,
+    metadata,
+    completion
+  };
+}
+
+export async function stopRun(homeDir, runId, { signal = "SIGTERM" } = {}) {
+  const state = await readRunState(homeDir, runId);
+  if (!state) {
+    throw new Error(`Run "${runId}" not found.`);
+  }
+
+  if (state.state === RUN_STATES.COMPLETED || state.state === RUN_STATES.FAILED || state.state === RUN_STATES.CANCELLED) {
+    return state;
+  }
+
+  const lock = await readSupervisorLock(homeDir, runId);
+  const child = activeProcesses.get(runId);
+
+  if (child) {
+    child.kill(signal);
+  } else {
+    const targets = [lock?.agentPid, state.pid, lock?.supervisorPid].filter(Boolean);
+    for (const pid of targets) {
+      try {
+        process.kill(pid, signal);
+      } catch {
+        // Process may already be gone.
+      }
+    }
+  }
+
+  await writeCancelSignal(homeDir, runId, {
+    requested: true,
+    signal,
+    requestedAt: new Date().toISOString()
+  });
+  await deleteRunHandoff(homeDir, runId);
+
+  const metadata = transitionRunState(state, RUN_STATES.CANCELLED, {
+    error: "Run cancelled by user."
+  });
+  cancelledRuns.add(runId);
+  await writeRunState(homeDir, metadata);
+  await appendRunEvent(homeDir, createRunEvent({
+    runId,
+    type: "run.cancelled",
+    data: { signal }
+  }));
+
+  activeProcesses.delete(runId);
+  return metadata;
+}
+
+export async function resolveRunAgent(profile, requestedAgent, detectedAgentIds = []) {
+  const agents = resolveProfileAgents(profile?.profile ?? profile, detectedAgentIds);
+  const runtime = resolveRuntimeOptions(profile, { agentId: requestedAgent });
+  const agentId = runtime.agentId ?? agents[0] ?? null;
+
+  if (!agentId) {
+    throw new Error("No agent specified and no default agent available.");
+  }
+
+  return { agentId, runtime };
+}

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

@@ -0,0 +1,93 @@
+import { resolveProfileAgents } from "../profile.js";
+import { EXECUTION_ADAPTER_IDS } from "./execution-adapters/index.js";
+
+export function resolveRuntimeOptions(profileResolved, overrides = {}) {
+  const profile = profileResolved?.profile ?? profileResolved ?? {};
+  const agentAliases = profile.agentAliases ?? {};
+  const modelAliases = profile.modelAliases ?? {};
+
+  let agentId = overrides.agentId ?? profile.defaultRuntimeAgent ?? null;
+  if (agentId && agentAliases[agentId]) {
+    agentId = agentAliases[agentId];
+  }
+
+  let model = overrides.model ?? profile.preferredModel ?? profile.defaultRuntimeModel ?? null;
+  if (model && modelAliases[model]) {
+    model = modelAliases[model];
+  }
+
+  const permissions = overrides.permissions
+    ?? profile.defaultPermissions
+    ?? [];
+
+  const captureTranscript = overrides.captureTranscript
+    ?? profile.captureTranscript
+    ?? false;
+
+  return {
+    agentId,
+    model,
+    permissions: Array.isArray(permissions) ? permissions : [],
+    captureTranscript: captureTranscript === true
+  };
+}
+
+export function validateRuntimeProfile(profile) {
+  const agentAliases = profile.agentAliases;
+  if (agentAliases != null) {
+    if (typeof agentAliases !== "object" || Array.isArray(agentAliases)) {
+      throw new Error("Profile agentAliases must be an object.");
+    }
+    for (const target of Object.values(agentAliases)) {
+      if (!EXECUTION_ADAPTER_IDS.includes(target)) {
+        throw new Error(`Unknown agent alias target "${target}".`);
+      }
+    }
+  }
+
+  const modelAliases = profile.modelAliases;
+  if (modelAliases != null) {
+    if (typeof modelAliases !== "object" || Array.isArray(modelAliases)) {
+      throw new Error("Profile modelAliases must be an object.");
+    }
+  }
+
+  const defaultPermissions = profile.defaultPermissions;
+  if (defaultPermissions != null && !Array.isArray(defaultPermissions)) {
+    throw new Error("Profile defaultPermissions must be an array.");
+  }
+
+  if (
+    profile.defaultRuntimeAgent != null
+    && !EXECUTION_ADAPTER_IDS.includes(profile.defaultRuntimeAgent)
+    && !Object.keys(agentAliases ?? {}).includes(profile.defaultRuntimeAgent)
+  ) {
+    throw new Error(`Unknown defaultRuntimeAgent "${profile.defaultRuntimeAgent}".`);
+  }
+
+  if (profile.captureTranscript != null && typeof profile.captureTranscript !== "boolean") {
+    throw new Error("Profile captureTranscript must be a boolean.");
+  }
+}
+
+export function resolveAgentFromProfile(profileResolved, requestedAgent) {
+  const runtime = resolveRuntimeOptions(profileResolved, { agentId: requestedAgent });
+  if (!runtime.agentId) {
+    throw new Error(`Unknown or missing agent. Use ${EXECUTION_ADAPTER_IDS.join(", ")}.`);
+  }
+  if (!EXECUTION_ADAPTER_IDS.includes(runtime.agentId)) {
+    throw new Error(`Agent "${runtime.agentId}" is not supported for Kairo runs.`);
+  }
+  return runtime;
+}
+
+export const RUNTIME_PROFILE_KEYS = new Set([
+  "agentAliases",
+  "modelAliases",
+  "defaultPermissions",
+  "defaultRuntimeAgent",
+  "defaultRuntimeModel",
+  "captureTranscript"
+]);
+
+export const SUPPORTED_RUN_AGENTS = [...EXECUTION_ADAPTER_IDS];

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

@@ -0,0 +1,66 @@
+import { isForbiddenSecretKey, normalizeProfileKey } from "../profile.js";
+
+const REDACTED = "[REDACTED]";
+
+const SECRET_VALUE_PATTERN = /^(sk-[A-Za-z0-9]|sk-or-|gh[pousr]_|xox[baprs]-|AKIA[0-9A-Z]{16}\b|Bearer\s+\S+|eyJ[A-Za-z0-9_-]+\.)|-----BEGIN [A-Z ]*PRIVATE KEY-----/i;
+
+const SENSITIVE_ENV_KEYS = new Set([
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "CURSOR_API_KEY",
+  "OPENROUTER_API_KEY",
+  "GITHUB_TOKEN",
+  "GH_TOKEN",
+  "AWS_SECRET_ACCESS_KEY",
+  "AWS_ACCESS_KEY_ID"
+]);
+
+export function redactString(value) {
+  if (typeof value !== "string" || value.length === 0) return value;
+  if (SECRET_VALUE_PATTERN.test(value)) return REDACTED;
+  return value;
+}
+
+export function redactObject(value, { allowTranscript = false } = {}) {
+  if (value == null) return value;
+  if (typeof value === "string") return redactString(value);
+  if (Array.isArray(value)) {
+    return value.map((item) => redactObject(item, { allowTranscript }));
+  }
+  if (typeof value !== "object") return value;
+
+  const result = {};
+  for (const [key, nested] of Object.entries(value)) {
+    const normalizedKey = normalizeProfileKey(key);
+
+    if (!allowTranscript && (normalizedKey === "prompt" || normalizedKey === "response" || normalizedKey === "content")) {
+      result[key] = REDACTED;
+      continue;
+    }
+
+    if (isForbiddenSecretKey(key) || SENSITIVE_ENV_KEYS.has(key)) {
+      result[key] = REDACTED;
+      continue;
+    }
+
+    result[key] = redactObject(nested, { allowTranscript });
+  }
+
+  return result;
+}
+
+export function redactEnv(env = process.env) {
+  const result = {};
+  for (const [key, value] of Object.entries(env)) {
+    if (SENSITIVE_ENV_KEYS.has(key) || isForbiddenSecretKey(key)) {
+      result[key] = REDACTED;
+    } else {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+export function shouldPersistTranscript(captureTranscript) {
+  return captureTranscript === true;
+}

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

@@ -0,0 +1,13 @@
+import { RUN_STATES, STARTING_GRACE_MS } from "./run-types.js";
+
+export function isWithinStartingGrace(run, lock, nowMs = Date.now()) {
+  if (run?.state !== RUN_STATES.STARTING && run?.state !== RUN_STATES.PENDING) {
+    return false;
+  }
+
+  const anchor = lock?.startingAt ?? lock?.startedAt ?? run?.startedAt;
+  if (!anchor) return false;
+
+  const elapsed = nowMs - new Date(anchor).getTime();
+  return elapsed >= 0 && elapsed < STARTING_GRACE_MS;
+}