@kal-elsam/kairo-runtime 0.2.1 → 0.2.3

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

@@ -0,0 +1,159 @@
+import { existsSync } from "node:fs";
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { harnessHomePaths, runPaths } from "../paths.js";
+import { RUN_STATES, isActiveRunState } from "./run-types.js";
+import { createRunEvent } from "./run-events.js";
+
+const writeLocks = new Map();
+
+export function getRunsDir(homeDir) {
+  return harnessHomePaths(homeDir).runsDir;
+}
+
+export async function createRunRecord(homeDir, metadata) {
+  const { runDir, statePath } = runPaths(homeDir, metadata.runId);
+  await mkdir(runDir, { recursive: true });
+  await writeFile(statePath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+  return metadata;
+}
+
+export async function readRunState(homeDir, runId) {
+  const { statePath } = runPaths(homeDir, runId);
+  if (!existsSync(statePath)) return null;
+
+  try {
+    return JSON.parse(await readFile(statePath, "utf8"));
+  } catch (error) {
+    throw new Error(`Invalid run state at ${statePath}: ${error.message}`);
+  }
+}
+
+export async function writeRunState(homeDir, metadata) {
+  const key = metadata.runId;
+  const previous = writeLocks.get(key) ?? Promise.resolve();
+  const next = previous.then(async () => {
+    const { statePath, runDir } = runPaths(homeDir, metadata.runId);
+    await mkdir(runDir, { recursive: true });
+    await writeFile(statePath, `${JSON.stringify(metadata, null, 2)}\n`, "utf8");
+    return metadata;
+  });
+  writeLocks.set(key, next.catch(() => {}));
+  return next;
+}
+
+export async function appendRunEvent(homeDir, event, { captureTranscript = false } = {}) {
+  const { eventsPath, transcriptPath } = runPaths(homeDir, event.runId);
+  await mkdir(runPaths(homeDir, event.runId).runDir, { recursive: true });
+
+  const line = `${JSON.stringify(event)}\n`;
+  await appendFile(eventsPath, line, "utf8");
+
+  if (captureTranscript && event.type === "run.transcript") {
+    await appendFile(transcriptPath, line, "utf8");
+  }
+
+  return event;
+}
+
+export async function appendRunStartedEvent(homeDir, metadata) {
+  const event = createRunEvent({
+    runId: metadata.runId,
+    type: "run.started",
+    data: {
+      agentId: metadata.agentId,
+      provider: metadata.provider,
+      model: metadata.model,
+      cwd: metadata.cwd,
+      permissions: metadata.permissions,
+      taskDigest: metadata.taskDigest,
+      taskLength: metadata.taskLength
+    }
+  });
+
+  await appendRunEvent(homeDir, event);
+  return event;
+}
+
+export async function readRunEvents(homeDir, runId, { limit = null } = {}) {
+  const { eventsPath } = runPaths(homeDir, runId);
+  if (!existsSync(eventsPath)) return [];
+
+  const content = await readFile(eventsPath, "utf8");
+  const events = content
+    .split("\n")
+    .filter((line) => line.trim().length > 0)
+    .map((line, index) => {
+      try {
+        return JSON.parse(line);
+      } catch (error) {
+        return { parseError: true, line: index + 1, message: error.message };
+      }
+    });
+
+  if (limit != null && limit > 0) {
+    return events.slice(-limit);
+  }
+
+  return events;
+}
+
+export async function listRunRecords(homeDir, { limit = null, activeOnly = false } = {}) {
+  const runsDir = getRunsDir(homeDir);
+  if (!existsSync(runsDir)) return [];
+
+  const entries = await readdir(runsDir, { withFileTypes: true });
+  const runs = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const state = await readRunState(homeDir, entry.name);
+    if (!state) continue;
+    if (activeOnly && !isActiveRunState(state.state)) continue;
+    runs.push(state);
+  }
+
+  runs.sort((left, right) => String(right.startedAt).localeCompare(String(left.startedAt)));
+
+  if (limit != null && limit > 0) {
+    return runs.slice(0, limit);
+  }
+
+  return runs;
+}
+
+export async function markInterruptedRuns(homeDir, { exceptRunIds = [] } = {}) {
+  const except = new Set(exceptRunIds);
+  return reconcileActiveRuns(homeDir, {
+    isRunAliveImpl: async (_dir, run) => except.has(run.runId)
+  });
+}
+
+export async function reconcileActiveRuns(homeDir, { isRunAliveImpl } = {}) {
+  const activeRuns = await listRunRecords(homeDir, { activeOnly: true });
+  const interrupted = [];
+
+  for (const run of activeRuns) {
+    if (isRunAliveImpl) {
+      const alive = await isRunAliveImpl(homeDir, run);
+      if (alive) continue;
+    }
+
+    const next = {
+      ...run,
+      state: RUN_STATES.INTERRUPTED,
+      updatedAt: new Date().toISOString(),
+      completedAt: new Date().toISOString(),
+      error: run.error ?? "Run interrupted (supervisor no longer alive)."
+    };
+    await writeRunState(homeDir, next);
+    const event = createRunEvent({
+      runId: run.runId,
+      type: "run.failed",
+      data: { reason: "interrupted", previousState: run.state }
+    });
+    await appendRunEvent(homeDir, event);
+    interrupted.push(next);
+  }
+
+  return interrupted;
+}

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

@@ -0,0 +1,37 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { runPaths } from "../paths.js";
+
+function lockPath(homeDir, runId) {
+  return `${runPaths(homeDir, runId).runDir}/supervisor.lock.json`;
+}
+
+export async function writeSupervisorLock(homeDir, runId, lock) {
+  const { runDir } = runPaths(homeDir, runId);
+  await mkdir(runDir, { recursive: true });
+  await writeFile(lockPath(homeDir, runId), `${JSON.stringify(lock, null, 2)}\n`, "utf8");
+}
+
+export async function readSupervisorLock(homeDir, runId) {
+  const path = lockPath(homeDir, runId);
+  if (!existsSync(path)) return null;
+
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function touchSupervisorLock(homeDir, runId, fields = {}) {
+  const current = await readSupervisorLock(homeDir, runId);
+  if (!current) return null;
+
+  const next = {
+    ...current,
+    ...fields,
+    lastHeartbeat: new Date().toISOString()
+  };
+  await writeSupervisorLock(homeDir, runId, next);
+  return next;
+}

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

@@ -0,0 +1,12 @@
+import { supervisePreparedRun } from "./run-supervisor.js";
+import { deleteRunHandoff } from "./run-handoff.js";
+
+const homeDir = process.env.KAIRO_SUPERVISOR_HOME;
+const runId = process.env.KAIRO_SUPERVISOR_RUN_ID;
+
+if (homeDir && runId) {
+  supervisePreparedRun({ homeDir, runId }).catch(async () => {
+    await deleteRunHandoff(homeDir, runId).catch(() => {});
+    process.exitCode = 1;
+  });
+}

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

@@ -0,0 +1,289 @@
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { RUN_STATES } from "./run-types.js";
+import {
+  applyEventToMetadata,
+  createRunEvent,
+  normalizeAdapterEvent,
+  transitionRunState
+} from "./run-events.js";
+import {
+  appendRunEvent,
+  readRunState,
+  writeRunState
+} from "./run-store.js";
+import { resolveExecutionAdapter } from "./execution-adapters/index.js";
+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";
+
+async function shouldPreserveCancelledState(homeDir, runId) {
+  const fresh = await readRunState(homeDir, runId);
+  if (fresh?.state === RUN_STATES.CANCELLED) {
+    return fresh;
+  }
+  if (await isRunCancelRequested(homeDir, runId)) {
+    return fresh ?? null;
+  }
+  return null;
+}
+
+const workerPath = fileURLToPath(new URL("./run-supervisor-worker.js", import.meta.url));
+
+export function spawnDetachedSupervisor({ homeDir, runId, spawnImpl = spawn }) {
+  const child = spawnImpl(process.execPath, [workerPath], {
+    env: {
+      ...process.env,
+      KAIRO_SUPERVISOR_HOME: homeDir,
+      KAIRO_SUPERVISOR_RUN_ID: runId
+    },
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+  return child.pid ?? null;
+}
+
+export const forkDetachedSupervisor = spawnDetachedSupervisor;
+
+export async function supervisePreparedRun({
+  homeDir,
+  runId,
+  follow = false,
+  timeoutMs = null,
+  spawnImpl = spawn,
+  cancelledRuns = null,
+  activeProcesses = null
+}) {
+  const handoff = await consumeRunHandoff(homeDir, runId);
+  const adapter = resolveExecutionAdapter(handoff.agentId);
+  let metadata = await readRunState(homeDir, runId);
+
+  if (!metadata) {
+    throw new Error(`Run "${runId}" not found.`);
+  }
+
+  const captureTranscript = handoff.captureTranscript === true;
+  const launch = adapter.buildLaunch({
+    task: handoff.task,
+    cwd: handoff.cwd,
+    model: handoff.model,
+    permissions: handoff.permissions ?? [],
+    profile: handoff.profile ?? null
+  });
+
+  metadata = {
+    ...metadata,
+    state: RUN_STATES.RUNNING,
+    supervisorPid: process.pid,
+    updatedAt: new Date().toISOString()
+  };
+  await writeRunState(homeDir, metadata);
+  await writeSupervisorLock(homeDir, runId, {
+    supervisorPid: process.pid,
+    agentPid: null,
+    startedAt: new Date().toISOString(),
+    lastHeartbeat: new Date().toISOString()
+  });
+
+  const child = spawnImpl(launch.command, launch.args, {
+    cwd: launch.cwd,
+    env: launch.env,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  activeProcesses?.set(runId, child);
+
+  let stdoutBuffer = "";
+  let stderrBuffer = "";
+  let timeoutHandle = null;
+  let processing = Promise.resolve();
+  let stateWrites = Promise.resolve();
+
+  const enqueue = (work) => {
+    processing = processing.then(work);
+  };
+
+  const serializeStateWrite = (work) => {
+    stateWrites = stateWrites.then(work);
+    return stateWrites;
+  };
+
+  const persistEvent = async (event) => {
+    await serializeStateWrite(async () => {
+      metadata = applyEventToMetadata(metadata, event);
+      await appendRunEvent(homeDir, event, { captureTranscript: shouldPersistTranscript(captureTranscript) });
+      await writeRunState(homeDir, metadata);
+    });
+  };
+
+  const handleLine = async (line, stream) => {
+    const structured = adapter.parseEventLine(line, { runId, cwd: handoff.cwd });
+    const normalized = structured
+      ? normalizeAdapterEvent(adapter.id, structured, { captureTranscript })
+      : normalizeAdapterEvent(adapter.id, line, { captureTranscript });
+
+    if (!normalized) return;
+
+    const event = {
+      ...normalized,
+      runId,
+      timestamp: normalized.timestamp ?? new Date().toISOString()
+    };
+
+    if (captureTranscript && (event.type === "agent.assistant" || event.type === "agent.result")) {
+      await persistEvent({
+        ...createRunEvent({
+          runId,
+          type: "run.transcript",
+          data: event.data,
+          captureTranscript: true
+        }),
+        runId,
+        timestamp: event.timestamp
+      });
+    }
+
+    await persistEvent(event);
+
+    if (follow && stream === "stdout") {
+      process.stdout.write(`${line}\n`);
+    }
+    if (follow && stream === "stderr") {
+      process.stderr.write(`${line}\n`);
+    }
+  };
+
+  const flushBuffer = async (buffer, stream) => {
+    const lines = buffer.split("\n");
+    const remainder = lines.pop() ?? "";
+    for (const line of lines) {
+      await handleLine(line, stream);
+    }
+    return remainder;
+  };
+
+  const completion = new Promise((resolve, reject) => {
+    child.on("error", async (error) => {
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+      activeProcesses?.delete(runId);
+
+      await serializeStateWrite(async () => {
+        const preserved = await shouldPreserveCancelledState(homeDir, runId);
+        if (preserved) {
+          cancelledRuns?.delete(runId);
+          resolve(preserved.state === RUN_STATES.CANCELLED
+            ? preserved
+            : { ...preserved, state: RUN_STATES.CANCELLED });
+          return;
+        }
+
+        metadata = transitionRunState(metadata, RUN_STATES.FAILED, {
+          error: error.message
+        });
+        await writeRunState(homeDir, metadata);
+        await appendRunEvent(homeDir, createRunEvent({
+          runId,
+          type: "run.failed",
+          data: { error: error.message }
+        }), { captureTranscript: shouldPersistTranscript(captureTranscript) });
+      });
+      reject(error);
+    });
+
+    child.on("close", async (exitCode) => {
+      try {
+        if (timeoutHandle) clearTimeout(timeoutHandle);
+        activeProcesses?.delete(runId);
+
+        await processing;
+        await stateWrites;
+
+        if (stdoutBuffer.trim()) {
+          await handleLine(stdoutBuffer.trim(), "stdout");
+          stdoutBuffer = "";
+        }
+        if (stderrBuffer.trim()) {
+          await handleLine(stderrBuffer.trim(), "stderr");
+          stderrBuffer = "";
+        }
+
+        await processing;
+        await stateWrites;
+
+        await serializeStateWrite(async () => {
+          const preserved = await shouldPreserveCancelledState(homeDir, runId);
+          if (preserved) {
+            cancelledRuns?.delete(runId);
+            resolve(preserved.state === RUN_STATES.CANCELLED
+              ? preserved
+              : { ...preserved, state: RUN_STATES.CANCELLED });
+            return;
+          }
+
+          if (cancelledRuns?.has(runId)) {
+            cancelledRuns.delete(runId);
+            try {
+              resolve(await readRunState(homeDir, runId));
+            } catch {
+              resolve({ ...metadata, state: RUN_STATES.CANCELLED });
+            }
+            return;
+          }
+
+          const failed = exitCode !== 0;
+          const nextState = failed ? RUN_STATES.FAILED : RUN_STATES.COMPLETED;
+          metadata = transitionRunState(metadata, nextState, {
+            exitCode,
+            error: failed ? `Process exited with code ${exitCode}` : null
+          });
+          await writeRunState(homeDir, metadata);
+          await appendRunEvent(homeDir, createRunEvent({
+            runId,
+            type: failed ? "run.failed" : "run.completed",
+            data: { exitCode }
+          }), { captureTranscript: shouldPersistTranscript(captureTranscript) });
+          resolve(metadata);
+        });
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+
+  child.stdout.on("data", (chunk) => {
+    enqueue(async () => {
+      stdoutBuffer += chunk.toString();
+      stdoutBuffer = await flushBuffer(stdoutBuffer, "stdout");
+    });
+  });
+
+  child.stderr.on("data", (chunk) => {
+    enqueue(async () => {
+      stderrBuffer += chunk.toString();
+      stderrBuffer = await flushBuffer(stderrBuffer, "stderr");
+    });
+  });
+
+  if (timeoutMs != null && timeoutMs > 0) {
+    timeoutHandle = setTimeout(() => {
+      child.kill("SIGTERM");
+    }, timeoutMs);
+  }
+
+  void serializeStateWrite(async () => {
+    metadata = {
+      ...metadata,
+      pid: child.pid ?? null
+    };
+    await writeRunState(homeDir, metadata);
+    await touchSupervisorLock(homeDir, runId, { agentPid: child.pid ?? null });
+  });
+
+  return completion;
+}
+
+export async function readSupervisorLockForRun(homeDir, runId) {
+  return readSupervisorLock(homeDir, runId);
+}

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

@@ -0,0 +1,117 @@
+import { createHash } from "node:crypto";
+
+export const RUN_STATES = {
+  PENDING: "pending",
+  STARTING: "starting",
+  RUNNING: "running",
+  COMPLETED: "completed",
+  FAILED: "failed",
+  CANCELLED: "cancelled",
+  INTERRUPTED: "interrupted"
+};
+
+export const STARTING_GRACE_MS = 30_000;
+
+export const RUN_EVENT_TYPES = {
+  RUN_STARTED: "run.started",
+  RUN_COMPLETED: "run.completed",
+  RUN_FAILED: "run.failed",
+  RUN_CANCELLED: "run.cancelled",
+  STDOUT: "process.stdout",
+  STDERR: "process.stderr",
+  TOOL_CALL: "agent.tool_call",
+  TOOL_RESULT: "agent.tool_result",
+  ASSISTANT: "agent.assistant",
+  TOKEN_USAGE: "agent.token_usage",
+  DIFF_SUMMARY: "agent.diff_summary",
+  SYSTEM: "agent.system",
+  RESULT: "agent.result",
+  TRANSCRIPT: "run.transcript"
+};
+
+export const TERMINAL_RUN_STATES = new Set([
+  RUN_STATES.COMPLETED,
+  RUN_STATES.FAILED,
+  RUN_STATES.CANCELLED,
+  RUN_STATES.INTERRUPTED
+]);
+
+export const ACTIVE_RUN_STATES = new Set([
+  RUN_STATES.PENDING,
+  RUN_STATES.STARTING,
+  RUN_STATES.RUNNING
+]);
+
+export function isTerminalRunState(state) {
+  return TERMINAL_RUN_STATES.has(state);
+}
+
+export function isActiveRunState(state) {
+  return state === RUN_STATES.PENDING
+    || state === RUN_STATES.STARTING
+    || state === RUN_STATES.RUNNING;
+}
+
+export function createRunId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).slice(2, 8);
+  return `run_${timestamp}_${random}`;
+}
+
+export function createTaskFingerprint(task) {
+  const normalized = String(task ?? "").replace(/\s+/g, " ").trim();
+  const digest = createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  return {
+    taskDigest: digest,
+    taskLength: normalized.length
+  };
+}
+
+export function formatTaskLabel(metadata) {
+  const digest = metadata?.taskDigest ?? "unknown";
+  const length = metadata?.taskLength ?? 0;
+  return `task:${digest} (${length} chars, content not stored)`;
+}
+
+export function createRunMetadata({
+  runId,
+  agentId,
+  provider,
+  model = null,
+  task,
+  cwd,
+  permissions = [],
+  captureTranscript = false,
+  cliVersion,
+  profileSources = null
+}) {
+  const { taskDigest, taskLength } = createTaskFingerprint(task);
+  const now = new Date().toISOString();
+
+  return {
+    runId,
+    agentId,
+    provider,
+    model,
+    taskDigest,
+    taskLength,
+    cwd,
+    permissions,
+    captureTranscript,
+    cliVersion,
+    profileSources,
+    state: RUN_STATES.PENDING,
+    pid: null,
+    supervisorPid: null,
+    exitCode: null,
+    startedAt: now,
+    updatedAt: now,
+    completedAt: null,
+    tools: [],
+    commands: [],
+    tokenUsage: null,
+    cost: null,
+    diffSummary: null,
+    error: null
+  };
+}

package/src/global/setup.js

@@ -1,5 +1,5 @@
 import { stdin as input, stdout as output } from "node:process";
-import { BRAND } from "./brand/index.js";
+import { BRAND, ONBOARDING_COPY } from "./brand/index.js";
 import { installGlobalHarness } from "./global-installer.js";
 import {
   assertExplicitApplyConsent,
@@ -59,6 +59,7 @@ export async function runHarnessSetup({
   confirmExplicit = false,
   json = false,
   simple = false,
+  onboarding = false,
   interactive = Boolean(input.isTTY && output.isTTY),
   createPrompt = createReadlinePrompt,
   runSetupInkImpl = defaultRunSetupInk,
@@ -76,7 +77,7 @@ export async function runHarnessSetup({
   let usedInk = false;
 
   if (!useInk && !useWizard) {
-    printSetupIntro({ homeDir });
+    printSetupIntro({ homeDir, onboarding });
   }
 
   const setupUiArgs = {
@@ -86,6 +87,7 @@ export async function runHarnessSetup({
     packageName,
     cliVersion,
     dryRun,
+    onboarding,
     preflight,
     yes,
     confirm,
@@ -254,11 +256,17 @@ export async function runHarnessSetup({
   return { cancelled: false, result, usedWizard, usedInk };
 }
 
-function printSetupIntro({ homeDir }) {
+function printSetupIntro({ homeDir, onboarding = false }) {
   const detected = detectInstalledAdapters({ homeDir });
 
-  console.log(`${BRAND.displayName} setup — local AI ecosystem configurator`);
-  console.log("Configures and coordinates local agents. Does not install the AI apps themselves.");
+  if (onboarding) {
+    console.log(ONBOARDING_COPY.welcomeTitle);
+    console.log(ONBOARDING_COPY.purpose);
+    console.log(ONBOARDING_COPY.safety);
+  } else {
+    console.log(`${BRAND.displayName} setup — local AI ecosystem configurator`);
+    console.log("Configures and coordinates local agents. Does not install the AI apps themselves.");
+  }
   console.log("");
   console.log(`Detected agents: ${detected.join(", ") || "none"}`);
   console.log(`Supported agents: ${GLOBAL_AGENT_IDS.join(", ")}`);