@kal-elsam/kairo-runtime 0.2.1 → 0.2.2

package/src/global/runtime/execution-adapters/create-execution-adapter.js

@@ -0,0 +1,92 @@
+import { isExecutableAvailable } from "../../cli-probe.js";
+
+export function createExecutionAdapter({
+  id,
+  label,
+  executable,
+  capabilities,
+  buildLaunch,
+  parseEventLine = null,
+  checkAvailability = null,
+  launchable = null
+}) {
+  return {
+    id,
+    label,
+    executable,
+    capabilities: {
+      structuredEvents: false,
+      tokens: false,
+      diff: false,
+      cancel: true,
+      transcript: false,
+      ...capabilities
+    },
+
+    availability(context = {}) {
+      if (checkAvailability) {
+        return checkAvailability(context);
+      }
+
+      const available = isExecutableAvailable(executable, { env: context.env ?? process.env });
+      if (!available) {
+        return {
+          available: false,
+          compatible: false,
+          launchable: false,
+          reason: `${label} CLI "${executable}" is not on PATH.`
+        };
+      }
+
+      if (!capabilities.structuredEvents) {
+        return {
+          available: true,
+          compatible: false,
+          launchable: launchable ?? false,
+          reason: `${label} can be launched but does not emit auditable structured events in v1.`
+        };
+      }
+
+      return {
+        available: true,
+        compatible: true,
+        launchable: launchable ?? true,
+        reason: null
+      };
+    },
+
+    buildLaunch(options) {
+      return buildLaunch(options);
+    },
+
+    parseEventLine(line, context = {}) {
+      if (!parseEventLine) return null;
+      return parseEventLine(line, context);
+    }
+  };
+}
+
+export function parseNdjsonLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+export function buildPermissionsArgs(permissions = []) {
+  const normalized = new Set(permissions.map((entry) => String(entry).toLowerCase()));
+
+  if (normalized.has("all") || normalized.has("force")) {
+    return ["--force"];
+  }
+
+  if (normalized.has("yolo") || normalized.has("dangerously-skip-permissions")) {
+    return ["--dangerously-skip-permissions"];
+  }
+
+  return [];
+}

package/src/global/runtime/execution-adapters/cursor.js

@@ -0,0 +1,104 @@
+import { createExecutionAdapter, parseNdjsonLine, buildPermissionsArgs } from "./create-execution-adapter.js";
+import { isExecutableAvailable } from "../../cli-probe.js";
+
+const EXECUTABLE = "cursor-agent";
+
+function checkCursorAvailability() {
+  const agentAvailable = isExecutableAvailable(EXECUTABLE);
+  if (!agentAvailable) {
+    const legacy = isExecutableAvailable("cursor");
+    if (!legacy) {
+      return {
+        available: false,
+        compatible: false,
+        launchable: false,
+        reason: 'Cursor agent CLI "cursor-agent" is not on PATH. Install Cursor CLI.'
+      };
+    }
+    return {
+      available: true,
+      compatible: false,
+      launchable: false,
+      reason: 'Found "cursor" but Kairo v1 requires "cursor-agent" for auditable non-interactive runs.'
+    };
+  }
+
+  return {
+    available: true,
+    compatible: true,
+    launchable: true,
+    reason: null
+  };
+}
+
+function buildCursorLaunch({ task, cwd, model, permissions = [] }) {
+  const args = [
+    "-p",
+    "--output-format",
+    "stream-json",
+    ...buildPermissionsArgs(permissions),
+    task
+  ];
+
+  if (model) {
+    args.unshift("--model", model);
+  }
+
+  return {
+    command: EXECUTABLE,
+    args,
+    cwd,
+    env: process.env
+  };
+}
+
+function parseCursorEventLine(line) {
+  const parsed = parseNdjsonLine(line);
+  if (!parsed || typeof parsed !== "object") return null;
+
+  if (parsed.type === "assistant" && parsed.timestamp_ms == null && parsed.model_call_id) {
+    return null;
+  }
+
+  if (parsed.type === "assistant" && parsed.timestamp_ms == null && !parsed.model_call_id) {
+    return null;
+  }
+
+  if (parsed.type === "tool_call") {
+    const toolName = parsed.tool_name ?? parsed.name ?? parsed.tool ?? "unknown";
+    return {
+      type: "tool_call",
+      tool_name: toolName,
+      status: parsed.subtype ?? parsed.status ?? "started",
+      id: parsed.call_id ?? parsed.id ?? null
+    };
+  }
+
+  if (parsed.type === "result" && parsed.usage) {
+    return {
+      type: "usage",
+      inputTokens: parsed.usage.input_tokens ?? parsed.usage.inputTokens ?? null,
+      outputTokens: parsed.usage.output_tokens ?? parsed.usage.outputTokens ?? null,
+      totalTokens: parsed.usage.total_tokens ?? parsed.usage.totalTokens ?? null,
+      cost: parsed.usage.cost ?? parsed.cost ?? null
+    };
+  }
+
+  return parsed;
+}
+
+export default createExecutionAdapter({
+  id: "cursor",
+  label: "Cursor",
+  executable: EXECUTABLE,
+  capabilities: {
+    structuredEvents: true,
+    tokens: true,
+    diff: false,
+    cancel: true,
+    transcript: true
+  },
+  checkAvailability: checkCursorAvailability,
+  buildLaunch: buildCursorLaunch,
+  parseEventLine: parseCursorEventLine
+});

package/src/global/runtime/execution-adapters/index.js

@@ -0,0 +1,36 @@
+import cursor from "./cursor.js";
+import codex from "./codex.js";
+import claude from "./claude.js";
+import opencode from "./opencode.js";
+
+const EXECUTION_ADAPTERS = [cursor, codex, claude, opencode];
+
+export const EXECUTION_ADAPTER_IDS = EXECUTION_ADAPTERS.map((adapter) => adapter.id);
+
+export function listExecutionAdapters() {
+  return [...EXECUTION_ADAPTERS];
+}
+
+export function resolveExecutionAdapter(id) {
+  const adapter = EXECUTION_ADAPTERS.find((candidate) => candidate.id === id);
+  if (!adapter) {
+    throw new Error(`Unknown execution adapter "${id}". Use ${EXECUTION_ADAPTER_IDS.join(", ")}.`);
+  }
+  return adapter;
+}
+
+export function inspectExecutionAdapters(context = {}) {
+  return EXECUTION_ADAPTERS.map((adapter) => ({
+    id: adapter.id,
+    label: adapter.label,
+    executable: adapter.executable,
+    capabilities: adapter.capabilities,
+    ...adapter.availability(context)
+  }));
+}
+
+export function listLaunchableAdapterIds(context = {}) {
+  return inspectExecutionAdapters(context)
+    .filter((provider) => provider.launchable)
+    .map((provider) => provider.id);
+}

package/src/global/runtime/execution-adapters/opencode.js

@@ -0,0 +1,38 @@
+import { createExecutionAdapter } from "./create-execution-adapter.js";
+
+const EXECUTABLE = "opencode";
+
+function buildOpencodeLaunch({ task, cwd, model, permissions = [] }) {
+  const args = ["run", task];
+
+  if (model) {
+    args.unshift("--model", model);
+  }
+
+  if (permissions.includes("force") || permissions.includes("all")) {
+    args.unshift("--force");
+  }
+
+  return {
+    command: EXECUTABLE,
+    args,
+    cwd,
+    env: process.env
+  };
+}
+
+export default createExecutionAdapter({
+  id: "opencode",
+  label: "OpenCode",
+  executable: EXECUTABLE,
+  launchable: false,
+  capabilities: {
+    structuredEvents: false,
+    tokens: false,
+    diff: false,
+    cancel: true,
+    transcript: false
+  },
+  buildLaunch: buildOpencodeLaunch,
+  parseEventLine: null
+});

package/src/global/runtime/run-cancel-signal.js

@@ -0,0 +1,29 @@
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { runPaths } from "../paths.js";
+
+function cancelSignalPath(homeDir, runId) {
+  return `${runPaths(homeDir, runId).runDir}/cancel.signal.json`;
+}
+
+export async function writeCancelSignal(homeDir, runId, payload) {
+  const { runDir } = runPaths(homeDir, runId);
+  await mkdir(runDir, { recursive: true });
+  await writeFile(cancelSignalPath(homeDir, runId), `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+export async function readCancelSignal(homeDir, runId) {
+  const path = cancelSignalPath(homeDir, runId);
+  if (!existsSync(path)) return null;
+
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function isRunCancelRequested(homeDir, runId) {
+  const signal = await readCancelSignal(homeDir, runId);
+  return signal?.requested === true;
+}

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

@@ -0,0 +1,221 @@
+import { resolveHomeDir } from "../paths.js";
+import { resolveProfile } from "../profile.js";
+import { printJson } from "../json-output.js";
+import { BRAND, commandHeader } from "../brand/index.js";
+import { formatCliCommand } from "../brand/cli.js";
+import { inspectExecutionAdapters } from "./execution-adapters/index.js";
+import {
+  listRunRecords,
+  readRunEvents,
+  readRunState
+} from "./run-store.js";
+import {
+  recoverRuns,
+  resolveRunAgent,
+  startRun,
+  stopRun
+} from "./run-manager.js";
+import { isActiveRunState, formatTaskLabel } from "./run-types.js";
+import { resolveAgentFromProfile } from "./run-profile.js";
+
+export async function runGlobalRun(options, packageManifest, { startRunImpl = startRun } = {}) {
+  const homeDir = resolveHomeDir();
+  await recoverRuns(homeDir);
+
+  if (!options.task) {
+    throw new Error(`Missing task. Use: ${formatCliCommand('run --agent <id> --task "..."')}`);
+  }
+
+  const profileResolved = await resolveProfile({
+    homeDir,
+    workspaceRoot: options.cwd
+  });
+
+  const runtime = resolveAgentFromProfile(profileResolved, options.agent);
+  const permissions = options.permissions ?? runtime.permissions;
+  const captureTranscript = options.captureTranscript || runtime.captureTranscript;
+
+  const { runId, metadata, completion } = await startRunImpl({
+    homeDir,
+    agentId: runtime.agentId,
+    task: options.task,
+    cwd: options.cwd,
+    model: options.model ?? runtime.model,
+    permissions,
+    captureTranscript,
+    cliVersion: packageManifest.version,
+    profile: profileResolved,
+    follow: options.follow,
+    timeoutMs: options.timeoutMs,
+    wait: options.wait !== false
+  });
+
+  if (!options.json) {
+    console.log(commandHeader(`run started · ${metadata.agentId} · ${runId}`));
+    console.log(`Task: ${formatTaskLabel(metadata)}`);
+    console.log(`Cwd: ${metadata.cwd}`);
+    if (!options.wait) {
+      console.log(`Follow: ${formatCliCommand(`runs show ${runId} --follow`)}`);
+      return { runId, metadata };
+    }
+  } else if (!options.wait) {
+    printJson({ runId, metadata });
+    return { runId, metadata };
+  }
+
+  if (!completion) {
+    if (options.json) {
+      printJson({ runId, metadata });
+    }
+    return { runId, metadata };
+  }
+
+  const final = await completion;
+
+  if (options.json) {
+    printJson({ runId, metadata: final });
+  } else {
+    console.log(`Run ${final.state} (exit ${final.exitCode ?? "n/a"})`);
+  }
+
+  return { runId, metadata: final };
+}
+
+export async function runGlobalRuns(options, packageManifest) {
+  const homeDir = resolveHomeDir();
+  await recoverRuns(homeDir);
+
+  switch (options.runsAction ?? "list") {
+    case "list":
+      return runRunsList(homeDir, options);
+    case "show":
+      return runRunsShow(homeDir, options);
+    case "stop":
+      return runRunsStop(homeDir, options);
+    default:
+      throw new Error(`Unknown runs action "${options.runsAction}". Use list, show, or stop.`);
+  }
+}
+
+async function runRunsList(homeDir, options) {
+  const runs = await listRunRecords(homeDir, {
+    limit: options.limit,
+    activeOnly: options.activeOnly
+  });
+
+  if (options.json) {
+    printJson({ runs, providers: inspectExecutionAdapters({ cwd: options.cwd }) });
+    return { runs };
+  }
+
+  console.log(commandHeader("runs"));
+  const active = runs.filter((run) => isActiveRunState(run.state));
+  console.log(`Active: ${active.length} · Total shown: ${runs.length}`);
+  console.log("");
+
+  for (const run of runs) {
+    console.log(
+      `  ${run.runId}  ${run.state.padEnd(12)}  ${run.agentId.padEnd(10)}  ${formatTaskLabel(run)}`
+    );
+  }
+
+  if (runs.length === 0) {
+    console.log(`  (no runs yet — launch with ${formatCliCommand('run --agent cursor --task "..."')})`);
+  }
+
+  return { runs };
+}
+
+async function runRunsShow(homeDir, options) {
+  if (!options.runId) {
+    throw new Error(`Missing run id. Use: ${formatCliCommand("runs show <runId>")}`);
+  }
+
+  const metadata = await readRunState(homeDir, options.runId);
+  if (!metadata) {
+    throw new Error(`Run "${options.runId}" not found.`);
+  }
+
+  const events = await readRunEvents(homeDir, options.runId, { limit: options.limit });
+
+  if (options.json) {
+    printJson({ metadata, events });
+    return { metadata, events };
+  }
+
+  console.log(commandHeader(`run ${metadata.runId}`));
+  console.log(`Agent: ${metadata.agentId} (${metadata.provider})`);
+  console.log(`State: ${metadata.state}`);
+  console.log(`Model: ${metadata.model ?? "default"}`);
+  console.log(`Cwd: ${metadata.cwd}`);
+  console.log(`Started: ${metadata.startedAt}`);
+  if (metadata.completedAt) console.log(`Completed: ${metadata.completedAt}`);
+  if (metadata.tokenUsage) console.log(`Tokens: ${JSON.stringify(metadata.tokenUsage)}`);
+  if (metadata.diffSummary) console.log(`Diff: ${JSON.stringify(metadata.diffSummary)}`);
+  if (metadata.error) console.log(`Error: ${metadata.error}`);
+  console.log("");
+  console.log("Events:");
+
+  for (const event of events) {
+    if (event.parseError) {
+      console.log(`  [parse error line ${event.line}]`);
+      continue;
+    }
+    const summary = summarizeEvent(event);
+    console.log(`  ${event.timestamp}  ${event.type}  ${summary}`);
+    if (options.follow) {
+      // follow is for live runs; show replays events only
+    }
+  }
+
+  return { metadata, events };
+}
+
+async function runRunsStop(homeDir, options) {
+  if (!options.runId) {
+    throw new Error(`Missing run id. Use: ${formatCliCommand("runs stop <runId>")}`);
+  }
+
+  const metadata = await stopRun(homeDir, options.runId);
+
+  if (options.json) {
+    printJson({ metadata });
+    return { metadata };
+  }
+
+  console.log(commandHeader(`run ${metadata.runId} cancelled`));
+  console.log(`State: ${metadata.state}`);
+  return { metadata };
+}
+
+function summarizeEvent(event) {
+  if (event.type === "agent.tool_call") {
+    return event.data?.tool_name ?? event.data?.name ?? "tool";
+  }
+  if (event.type === "process.stdout" || event.type === "process.stderr") {
+    const line = event.data?.line ?? "";
+    return line.length > 80 ? `${line.slice(0, 79)}…` : line;
+  }
+  if (event.type === "run.completed" || event.type === "run.failed") {
+    return `exit=${event.data?.exitCode ?? "n/a"}`;
+  }
+  return "";
+}
+
+export async function buildRuntimeDashboardData({ homeDir, workspaceRoot, cliVersion }) {
+  await recoverRuns(homeDir);
+  const [runs, providers, profileResolved] = await Promise.all([
+    listRunRecords(homeDir, { limit: 20 }),
+    Promise.resolve(inspectExecutionAdapters({ cwd: workspaceRoot })),
+    resolveProfile({ homeDir, workspaceRoot })
+  ]);
+
+  return {
+    cliVersion,
+    runs,
+    activeRuns: runs.filter((run) => isActiveRunState(run.state)),
+    recentRuns: runs.filter((run) => !isActiveRunState(run.state)).slice(0, 10),
+    providers,
+    profile: profileResolved
+  };
+}

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
+  };
+}