@kal-elsam/kairo-runtime 0.4.3 → 0.5.0

package/src/global/integrations/engram-exec.js

@@ -0,0 +1,107 @@
+import { spawn } from "node:child_process";
+
+export const ENGRAM_SETUP_TIMEOUT_MS = 180_000;
+const LOG_LIMIT = 480;
+
+/** Absolute `engram setup <slug>` without shell. SIGTERM→SIGKILL on timeout. */
+export function runEngramSetup({
+  binaryPath,
+  slug,
+  env = process.env,
+  spawnImpl = spawn,
+  timeoutMs = ENGRAM_SETUP_TIMEOUT_MS,
+  terminationGraceMs = 1000,
+  killGraceMs = 1000
+} = {}) {
+  assertSafeSetupInvocation(binaryPath, slug);
+  const args = ["setup", slug];
+
+  return new Promise((resolve, reject) => {
+    const child = spawnImpl(binaryPath, args, { env, stdio: ["ignore", "pipe", "pipe"], shell: false });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let timedOut = false;
+    let timers = [];
+    const clearTimers = () => { for (const t of timers) clearTimeout(t); timers = []; };
+    const schedule = (fn, ms) => { timers.push(setTimeout(fn, ms)); };
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimers();
+      detachIo();
+      resolve(result);
+    };
+    const finish = ({ status = null, signal = null, terminationFailed = false } = {}) => {
+      settle({
+        ok: status === 0 && !timedOut && !terminationFailed,
+        command: [binaryPath, ...args],
+        slug, status, signal, timedOut, terminationFailed,
+        stdout: redactEngramLog(stdout),
+        stderr: redactEngramLog(stderr)
+      });
+    };
+    const onStdout = (c) => { stdout = appendLimited(stdout, c, LOG_LIMIT * 4); };
+    const onStderr = (c) => { stderr = appendLimited(stderr, c, LOG_LIMIT); };
+    const onError = (error) => {
+      if (settled) return;
+      settled = true; clearTimers(); detachIo(); reject(error);
+    };
+    const onClose = (status, signal) => finish({ status: status ?? null, signal: signal ?? null });
+    const detachIo = () => {
+      child.stdout?.off?.("data", onStdout);
+      child.stderr?.off?.("data", onStderr);
+      child.off?.("close", onClose);
+    };
+    schedule(() => {
+      if (settled) return;
+      timedOut = true;
+      safeKill(child, "SIGTERM");
+      schedule(() => {
+        if (settled) return;
+        safeKill(child, "SIGKILL");
+        schedule(() => {
+          if (settled) return;
+          try { child.unref?.(); } catch { /* ignore */ }
+          finish({ terminationFailed: true });
+        }, killGraceMs);
+      }, terminationGraceMs);
+    }, timeoutMs);
+    child.stdout?.on("data", onStdout);
+    child.stderr?.on("data", onStderr);
+    child.on("error", onError);
+    child.on("close", onClose);
+  });
+}
+
+export function assertSafeSetupInvocation(binaryPath, slug) {
+  if (typeof binaryPath !== "string" || !binaryPath.startsWith("/") || binaryPath.includes("\0")) {
+    throw new Error("Engram setup requires an absolute binary path.");
+  }
+  if (typeof slug !== "string" || !/^[a-z][a-z0-9-]*$/.test(slug)) {
+    throw new Error(`Invalid Engram setup slug "${slug}".`);
+  }
+  if (/engram\.db/i.test(binaryPath) || /engram\.db/i.test(slug)) {
+    throw new Error("Engram setup refuses paths that reference the memory database.");
+  }
+}
+
+export function redactEngramLog(text, { limit = LOG_LIMIT } = {}) {
+  let out = String(text ?? "").replace(/\s+/g, " ").trim();
+  out = out.replace(/\bBearer\s+\S+/gi, "Bearer [REDACTED]");
+  out = out.replace(/\b(sk-[A-Za-z0-9_-]+)\b/g, "[REDACTED]");
+  out = out.replace(/\b([A-Z][A-Z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL)[A-Z0-9_]*)\s*[:=]\s*\S+/gi, "$1=[REDACTED]");
+  if (out.length > limit) out = `${out.slice(0, Math.max(0, limit - 1))}…`;
+  return out;
+}
+
+function appendLimited(current, chunk, limit) {
+  if (current.length >= limit) return current;
+  const next = current + String(chunk);
+  return next.length > limit ? next.slice(0, limit) : next;
+}
+
+function safeKill(child, signal) {
+  try { return typeof child.kill === "function" ? child.kill(signal) !== false : false; }
+  catch { return false; }
+}

package/src/global/integrations/engram-plan.js

@@ -0,0 +1,60 @@
+import {
+  resolveEngramAgentSelection,
+  engramSetupSlugForAgent,
+  ENGRAM_INTEGRATION_STATUS,
+  inspectEngramIntegration
+} from "./engram-evidence.js";
+
+/** Dry-run / apply plan. Dry-run never writes or executes setup. */
+export function planEngramConfigure({
+  requestedAgentIds = null,
+  detectedAgentIds = [],
+  env = process.env,
+  homeDir,
+  inspect = inspectEngramIntegration,
+  dryRun = true
+} = {}) {
+  const agentIds = resolveEngramAgentSelection({ requestedIds: requestedAgentIds, detectedIds: detectedAgentIds });
+  const inspection = inspect({ env, homeDir, agentIds });
+  const { binary } = inspection;
+  const canSetup = binary.supported === true && Boolean(binary.path);
+
+  const actions = agentIds.map((agentId) => {
+    const agent = inspection.agents.find((entry) => entry.id === agentId) ?? {
+      id: agentId,
+      slug: engramSetupSlugForAgent(agentId),
+      status: ENGRAM_INTEGRATION_STATUS.UNCONFIGURED
+    };
+    const slug = agent.slug ?? engramSetupSlugForAgent(agentId);
+    let action = "setup";
+    let reason = "Official `engram setup` required.";
+    if (!canSetup) {
+      action = "blocked";
+      reason = binary.guidance ?? `Engram is ${binary.status}.`;
+    } else if (agent.status === ENGRAM_INTEGRATION_STATUS.CONFIGURED) {
+      action = "noop";
+      reason = "Already configured (idempotent re-setup still available on apply).";
+    } else if (agent.status === ENGRAM_INTEGRATION_STATUS.CONFLICT) {
+      reason = "Conflict detected; official setup may repair agent config.";
+    }
+    return {
+      agentId, slug, action, reason, status: agent.status,
+      command: canSetup ? [binary.path, "setup", slug] : null,
+      executes: false, writes: false
+    };
+  });
+
+  return {
+    provider: "engram",
+    componentId: "engram-memory",
+    dryRun: Boolean(dryRun),
+    executes: false,
+    writes: false,
+    binary,
+    agents: inspection.agents,
+    actions,
+    blocked: !canSetup,
+    guidance: binary.guidance,
+    nextStatusIfApplied: canSetup ? ENGRAM_INTEGRATION_STATUS.RESTART_REQUIRED : binary.status
+  };
+}

package/src/global/integrations/engram-provider.js

@@ -0,0 +1,22 @@
+import { inspectEngramIntegration } from "./engram-evidence.js";
+import { planEngramConfigure } from "./engram-plan.js";
+import {
+  applyEngramConfigureWithReceipt,
+  rollbackEngramReceipt
+} from "./engram-rollback.js";
+
+export function createEngramProvider({
+  inspect = inspectEngramIntegration,
+  plan = planEngramConfigure,
+  apply = applyEngramConfigureWithReceipt,
+  rollback = rollbackEngramReceipt
+} = {}) {
+  return {
+    id: "engram",
+    async inspect(context = {}) { return inspect(context); },
+    async plan(context = {}) { return plan(context); },
+    async apply(context = {}) { return apply(context); },
+    async verify(context = {}) { return inspect(context); },
+    async rollback(context = {}) { return rollback(context); }
+  };
+}

package/src/global/integrations/engram-receipts.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, readFile, writeFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { harnessHomePaths } from "../paths.js";
+import { inspectEngramAgentConfig } from "./engram-evidence.js";
+
+const MEMORY_DB = /engram\.db$/i;
+
+export function engramIntegrationsDir(homeDir) {
+  return join(harnessHomePaths(homeDir).root, "integrations", "engram");
+}
+
+export function engramReceiptPath(homeDir, receiptId) {
+  assertSafeReceiptId(receiptId);
+  return join(engramIntegrationsDir(homeDir), `${receiptId}.json`);
+}
+
+export function engramReceiptBackupDir(homeDir, receiptId) {
+  assertSafeReceiptId(receiptId);
+  return join(engramIntegrationsDir(homeDir), "backups", receiptId);
+}
+
+export function assertSafeReceiptId(receiptId) {
+  if (typeof receiptId !== "string" || !/^engram-[A-Za-z0-9-]+$/.test(receiptId)) {
+    throw new Error(`Invalid Engram receipt id "${receiptId}".`);
+  }
+}
+
+export function hashFileContents(contents) {
+  return createHash("sha256").update(contents).digest("hex");
+}
+
+export async function hashFileIfPresent(path) {
+  if (!existsSync(path)) return null;
+  if (MEMORY_DB.test(path)) throw new Error("Refusing to hash Engram memory database.");
+  return hashFileContents(await readFile(path));
+}
+
+export async function captureEngramObservedFiles(agentIds, { homeDir } = {}) {
+  const files = [];
+  for (const agentId of agentIds) {
+    for (const item of inspectEngramAgentConfig(agentId, { homeDir }).evidence) {
+      if (MEMORY_DB.test(item.path)) continue;
+      const hash = await hashFileIfPresent(item.path);
+      files.push({
+        agentId,
+        path: item.path,
+        kind: item.kind,
+        ownership: item.kind === "plugin" ? "provider" : "kairo",
+        present: hash != null,
+        hash
+      });
+    }
+  }
+  return files;
+}
+
+export function diffEngramObservedFiles(before = [], after = []) {
+  const beforeByPath = new Map(before.map((e) => [e.path, e]));
+  const afterByPath = new Map(after.map((e) => [e.path, e]));
+  const changes = [];
+  for (const path of new Set([...beforeByPath.keys(), ...afterByPath.keys()])) {
+    const prev = beforeByPath.get(path);
+    const next = afterByPath.get(path);
+    if (!prev?.present && next?.present) {
+      changes.push({
+        path, agentId: next.agentId, kind: next.kind, ownership: next.ownership,
+        change: "created", beforeHash: null, afterHash: next.hash
+      });
+    } else if (prev?.present && next?.present && prev.hash !== next.hash) {
+      changes.push({
+        path, agentId: next.agentId, kind: next.kind, ownership: next.ownership,
+        change: "modified", beforeHash: prev.hash, afterHash: next.hash
+      });
+    }
+  }
+  return changes;
+}
+
+export async function backupObservedFiles(before, { homeDir, receiptId } = {}) {
+  const backups = [];
+  const root = engramReceiptBackupDir(homeDir, receiptId);
+  for (const entry of before) {
+    if (!entry.present || entry.ownership !== "kairo") continue;
+    const backupPath = join(root, Buffer.from(entry.path).toString("base64url"));
+    await mkdir(root, { recursive: true });
+    await copyFile(entry.path, backupPath);
+    backups.push({ path: entry.path, backupPath, beforeHash: entry.hash });
+  }
+  return backups;
+}
+
+export async function saveEngramReceipt(receipt, { homeDir } = {}) {
+  assertSafeReceiptId(receipt.id);
+  if (receipt.touchedMemoryDb) {
+    throw new Error("Refusing to persist a receipt that touched the Engram memory database.");
+  }
+  await mkdir(engramIntegrationsDir(homeDir), { recursive: true });
+  const path = engramReceiptPath(homeDir, receipt.id);
+  const sanitized = { ...receipt, persisted: true };
+  await writeFile(path, `${JSON.stringify(sanitized, null, 2)}\n`, "utf8");
+  return { path, receipt: sanitized };
+}
+
+export async function loadEngramReceipt(receiptId, { homeDir } = {}) {
+  const path = engramReceiptPath(homeDir, receiptId);
+  if (!existsSync(path)) throw new Error(`Engram receipt not found: ${receiptId}`);
+  return JSON.parse(await readFile(path, "utf8"));
+}
+
+export async function listEngramReceipts({ homeDir } = {}) {
+  const dir = engramIntegrationsDir(homeDir);
+  if (!existsSync(dir)) return [];
+  return (await readdir(dir)).filter((n) => n.endsWith(".json")).map((n) => n.slice(0, -5)).sort();
+}

package/src/global/integrations/engram-rollback.js

@@ -0,0 +1,131 @@
+import { existsSync } from "node:fs";
+import { copyFile, mkdir, rm } from "node:fs/promises";
+import { dirname } from "node:path";
+import {
+  assertExplicitApplyConsent,
+  promptApplyConfirmation,
+  shouldPromptApplyConfirmation
+} from "../apply-confirmation.js";
+import { resolveHomeDir } from "../paths.js";
+import { applyEngramConfigure } from "./engram-apply.js";
+import {
+  backupObservedFiles,
+  captureEngramObservedFiles,
+  diffEngramObservedFiles,
+  hashFileIfPresent,
+  loadEngramReceipt,
+  saveEngramReceipt
+} from "./engram-receipts.js";
+
+/** Snapshot+backup before setup, then persist a secret-free receipt. */
+export async function applyEngramConfigureWithReceipt(options = {}) {
+  const homeDir = options.homeDir ?? resolveHomeDir();
+  const plannedAgents = options.requestedAgentIds ?? options.detectedAgentIds ?? [];
+  const receiptId = options.receiptId ?? `engram-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+  const before = options.dryRun ? [] : await captureEngramObservedFiles(plannedAgents, { homeDir });
+  const backups = options.dryRun ? [] : await backupObservedFiles(before, { homeDir, receiptId });
+
+  const result = await applyEngramConfigure({ ...options, homeDir, receiptId });
+  if (options.dryRun || result.cancelled || !result.receipt) return result;
+
+  const after = await captureEngramObservedFiles(result.receipt.agentsRequested, { homeDir });
+  const changes = diffEngramObservedFiles(before, after);
+  const receipt = {
+    ...result.receipt,
+    observedBefore: before,
+    observedAfter: after,
+    changes,
+    backups,
+    providerOwnedResidue: changes.filter((c) => c.ownership === "provider")
+  };
+  const saved = await saveEngramReceipt(receipt, { homeDir });
+  return { ...result, receipt: saved.receipt, receiptPath: saved.path };
+}
+
+export async function rollbackEngramReceipt({
+  receiptId,
+  homeDir,
+  dryRun = false,
+  yes = false,
+  json = false,
+  interactive = null,
+  confirm = promptApplyConfirmation
+} = {}) {
+  assertExplicitApplyConsent({
+    applying: !dryRun, dryRun, json, yes, interactive, command: "components rollback"
+  });
+  const receipt = await loadEngramReceipt(receiptId, { homeDir });
+  if (receipt.touchedMemoryDb) {
+    throw new Error("Receipt indicates memory DB access; refusing rollback.");
+  }
+
+  if (shouldPromptApplyConfirmation({ applying: true, dryRun, json, confirm: yes, interactive })) {
+    const accepted = await confirm({
+      command: `components rollback engram-memory --receipt ${receiptId}`,
+      question: `Rollback Engram receipt ${receiptId}? [Y/n]: `
+    });
+    if (!accepted) return { dryRun, cancelled: true, receiptId, actions: [] };
+  }
+
+  const actions = [];
+  for (const change of receipt.changes ?? []) {
+    if (change.ownership === "provider") {
+      actions.push({
+        path: change.path,
+        action: "residue",
+        ok: true,
+        reason: "Provider-owned plugin/marketplace artifact; not uninstalled automatically."
+      });
+      continue;
+    }
+    if (change.change === "modified") {
+      actions.push(await restoreModified(change, receipt, { dryRun }));
+      continue;
+    }
+    if (change.change === "created") {
+      actions.push(await deleteCreated(change, { dryRun }));
+    }
+  }
+
+  return {
+    dryRun,
+    cancelled: false,
+    receiptId,
+    ok: actions.every((a) => a.ok !== false),
+    actions,
+    touchedMemoryDb: false
+  };
+}
+
+async function restoreModified(change, receipt, { dryRun }) {
+  const currentHash = await hashFileIfPresent(change.path);
+  if (currentHash !== change.afterHash) {
+    return { path: change.path, action: "skip", ok: true, reason: "File changed after setup; refusing restore." };
+  }
+  const backup = (receipt.backups ?? []).find((entry) => entry.path === change.path);
+  if (!backup?.backupPath || !existsSync(backup.backupPath)) {
+    return { path: change.path, action: "skip", ok: false, reason: "Backup missing." };
+  }
+  if (!dryRun) {
+    await mkdir(dirname(change.path), { recursive: true });
+    await copyFile(backup.backupPath, change.path);
+  }
+  return { path: change.path, action: "restore", ok: true, backupPath: backup.backupPath };
+}
+
+async function deleteCreated(change, { dryRun }) {
+  const currentHash = await hashFileIfPresent(change.path);
+  if (currentHash == null) {
+    return { path: change.path, action: "skip", ok: true, reason: "Already absent." };
+  }
+  if (currentHash !== change.afterHash) {
+    return {
+      path: change.path,
+      action: "skip",
+      ok: true,
+      reason: "Created file was edited after setup; refusing delete."
+    };
+  }
+  if (!dryRun) await rm(change.path, { force: true });
+  return { path: change.path, action: "delete", ok: true };
+}

package/src/global/integrations/index.js

@@ -0,0 +1,12 @@
+import { createEngramProvider } from "./engram-provider.js";
+import { createSddCoreProvider } from "./sdd-provider.js";
+import { registerIntegrationProvider, getIntegrationProvider } from "./provider-registry.js";
+
+export function ensureIntegrationProvidersRegistered() {
+  if (!getIntegrationProvider("engram")) {
+    registerIntegrationProvider(createEngramProvider());
+  }
+  if (!getIntegrationProvider("sdd-core")) {
+    registerIntegrationProvider(createSddCoreProvider());
+  }
+}

package/src/global/integrations/provider-contract.js

@@ -0,0 +1,83 @@
+/** Integration provider contract — metadata only; no executable commands in manifests. */
+
+export const INTEGRATION_PROVIDER_IDS = Object.freeze(["engram", "sdd-core"]);
+export const PROVIDER_METHODS = Object.freeze(["inspect", "plan", "apply", "verify", "rollback"]);
+
+const EXECUTABLE_FIELDS = Object.freeze([
+  "commands",
+  "command",
+  "execute",
+  "bin",
+  "setup",
+  "apply",
+  "shell",
+  "argv",
+  "script",
+  "exec"
+]);
+
+export function assertProviderContract(provider) {
+  if (provider == null || typeof provider !== "object" || Array.isArray(provider)) {
+    throw new Error("Integration provider must be an object.");
+  }
+  if (typeof provider.id !== "string" || !INTEGRATION_PROVIDER_IDS.includes(provider.id)) {
+    throw new Error(
+      `Integration provider id must be one of: ${INTEGRATION_PROVIDER_IDS.join(", ")}.`
+    );
+  }
+  for (const method of PROVIDER_METHODS) {
+    if (typeof provider[method] !== "function") {
+      throw new Error(`Integration provider "${provider.id}" is missing ${method}().`);
+    }
+  }
+  return provider;
+}
+
+export function normalizeIntegrationMetadata(integration, { componentId, source = "bundled" } = {}) {
+  if (integration === undefined) return null;
+  if (!isObject(integration)) {
+    throw new Error(`Component "${componentId}" integration must be an object.`);
+  }
+
+  assertNoExecutableFields(integration, { componentId, source });
+
+  const { provider } = integration;
+  if (typeof provider !== "string" || !INTEGRATION_PROVIDER_IDS.includes(provider)) {
+    throw new Error(
+      `Component "${componentId}" integration.provider must be one of: ${INTEGRATION_PROVIDER_IDS.join(", ")}.`
+    );
+  }
+
+  const allowed = new Set(["provider"]);
+  for (const key of Object.keys(integration)) {
+    if (!allowed.has(key)) {
+      throw new Error(
+        `Component "${componentId}" integration declares unsupported field "${key}".`
+      );
+    }
+  }
+
+  return { provider };
+}
+
+function assertNoExecutableFields(integration, { componentId, source }) {
+  for (const key of Object.keys(integration)) {
+    const isExecutable = EXECUTABLE_FIELDS.includes(key)
+      || /Command$/i.test(key)
+      || /commands?/i.test(key);
+    if (!isExecutable) continue;
+
+    if (source === "workspace") {
+      throw new Error(
+        `Workspace component "${componentId}" cannot declare executable integration.${key}.`
+      );
+    }
+    throw new Error(
+      `Component "${componentId}" integration cannot declare executable field "${key}".`
+    );
+  }
+}
+
+function isObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}

package/src/global/integrations/provider-registry.js

@@ -0,0 +1,47 @@
+import { assertProviderContract } from "./provider-contract.js";
+
+const providers = new Map();
+
+export function registerIntegrationProvider(provider) {
+  assertProviderContract(provider);
+  if (providers.has(provider.id)) {
+    throw new Error(`Integration provider "${provider.id}" is already registered.`);
+  }
+  const frozen = Object.freeze({
+    id: provider.id,
+    inspect: provider.inspect,
+    plan: provider.plan,
+    apply: provider.apply,
+    verify: provider.verify,
+    rollback: provider.rollback
+  });
+  providers.set(provider.id, frozen);
+  return frozen;
+}
+
+export function getIntegrationProvider(id) {
+  return providers.get(id) ?? null;
+}
+
+export function requireIntegrationProvider(id) {
+  const provider = getIntegrationProvider(id);
+  if (!provider) {
+    throw new Error(`Unknown integration provider "${id}".`);
+  }
+  return provider;
+}
+
+export function listIntegrationProviders() {
+  return [...providers.values()];
+}
+
+export function resolveComponentIntegrationProvider(component) {
+  const providerId = component?.integration?.provider;
+  if (!providerId) return null;
+  return requireIntegrationProvider(providerId);
+}
+
+/** Test helper — clears registry between tests. */
+export function resetIntegrationProvidersForTests() {
+  providers.clear();
+}