@kal-elsam/kairo-runtime 0.4.2 → 0.5.0

package/src/global/integrations/sdd-state.js

@@ -0,0 +1,175 @@
+import { SDD_FILE_OUTCOMES } from "./sdd-evidence.js";
+import { derivePersona, normalizePersonaAgentIds } from "./sdd-persona.js";
+
+/** Empty v4 SDD block: persona off, no managed files, no receipt. */
+export function defaultSddState() {
+  return {
+    persona: "off",
+    personaAgentIds: [],
+    agentIds: [],
+    files: [],
+    lastReceiptId: null,
+    updatedAt: null
+  };
+}
+
+/** Coerce any prior/absent shape into a valid v4 SDD block. */
+export function normalizeSddState(raw) {
+  if (!raw || typeof raw !== "object") return defaultSddState();
+  const personaAgentIds = Object.hasOwn(raw, "personaAgentIds")
+    ? (Array.isArray(raw.personaAgentIds) ? normalizePersonaAgentIds(raw.personaAgentIds) : [])
+    : (raw.persona === "teaching" && Array.isArray(raw.agentIds)
+      ? normalizePersonaAgentIds(raw.agentIds) : []);
+  return {
+    persona: derivePersona(personaAgentIds),
+    personaAgentIds,
+    agentIds: Array.isArray(raw.agentIds) ? [...raw.agentIds] : [],
+    files: Array.isArray(raw.files) ? raw.files.map(normalizeSddFile) : [],
+    lastReceiptId: typeof raw.lastReceiptId === "string" ? raw.lastReceiptId : null,
+    updatedAt: typeof raw.updatedAt === "string" ? raw.updatedAt : null
+  };
+}
+
+function normalizeSddFile(entry) {
+  return {
+    destinationPath: entry.destinationPath,
+    relativePath: entry.relativePath ?? "SKILL.md",
+    skillId: entry.skillId,
+    agentIds: Array.isArray(entry.agentIds) ? [...entry.agentIds] : [],
+    hash: entry.hash ?? null,
+    skillHash: entry.skillHash ?? null,
+    action: entry.action ?? null
+  };
+}
+
+function verifiedNoopHash(file) {
+  const disk = file.afterHash ?? file.diskHash ?? file.beforeHash ?? null;
+  if (disk == null || file.canonicalHash == null || disk !== file.canonicalHash) return null;
+  return disk;
+}
+
+/** Track only applied(+afterHash) or noop with verified hash equality. No legacy fallback. */
+export function shouldTrackSddReceiptFile(file) {
+  if (!file || typeof file !== "object") return false;
+  if (file.outcome === SDD_FILE_OUTCOMES.APPLIED) return file.afterHash != null;
+  if (file.outcome === SDD_FILE_OUTCOMES.NOOP) return verifiedNoopHash(file) != null;
+  return false;
+}
+
+function trackingHash(file) {
+  if (file.outcome === SDD_FILE_OUTCOMES.APPLIED) return file.afterHash ?? null;
+  if (file.outcome === SDD_FILE_OUTCOMES.NOOP) return verifiedNoopHash(file);
+  return null;
+}
+
+function collectAgentIds(files) {
+  const ids = new Set();
+  for (const file of files) {
+    for (const id of file.agentIds ?? []) ids.add(id);
+  }
+  return [...ids].sort();
+}
+
+/** Legacy receipts without personaTransition derive consumers from teaching + files. */
+function resolvePersonaAgentIds(receipt, current, files) {
+  if (receipt?.personaTransition) return normalizePersonaAgentIds(receipt.personaTransition.after);
+  if (!files.length || (receipt.persona ?? current.persona) !== "teaching") return [];
+  return current.personaAgentIds.length ? current.personaAgentIds : collectAgentIds(files);
+}
+
+/** True when rollback mutated disk via successful delete/restore (even if global ok=false). */
+export function hasSuccessfulSddRollbackMutations(actions) {
+  return (actions ?? []).some((entry) =>
+    entry?.ok && !entry.noop && (entry.action === "delete" || entry.action === "restore" || entry.action === "persona")
+  );
+}
+
+/** Merge receipt into v4 SDD block for applied/verified files only. */
+export function recordSddMaterialization(state, { receipt, now = () => new Date().toISOString() } = {}) {
+  const current = normalizeSddState(state?.sdd);
+  const managed = new Map(current.files.map((file) => [file.destinationPath, file]));
+
+  for (const file of receipt.files ?? []) {
+    if (!shouldTrackSddReceiptFile(file)) continue;
+    const hash = trackingHash(file);
+    if (hash == null) continue;
+    managed.set(file.destinationPath, {
+      destinationPath: file.destinationPath,
+      relativePath: file.relativePath ?? "SKILL.md",
+      skillId: file.skillId,
+      agentIds: [...(file.agentIds ?? [])],
+      hash,
+      skillHash: file.skillHash ?? null,
+      action: file.action
+    });
+  }
+
+  const files = [...managed.values()].sort((left, right) =>
+    left.destinationPath.localeCompare(right.destinationPath)
+  );
+  const personaAgentIds = resolvePersonaAgentIds(receipt, current, files);
+
+  return {
+    ...(state ?? {}),
+    sdd: {
+      persona: derivePersona(personaAgentIds),
+      personaAgentIds,
+      agentIds: collectAgentIds(files),
+      files,
+      lastReceiptId: receipt.id ?? current.lastReceiptId,
+      updatedAt: now()
+    }
+  };
+}
+
+/** Reconcile each successful delete/restore/persona; refresh agentIds/persona from remaining files. */
+export function reconcileSddStateAfterRollback(state, {
+  receipt, actions, now = () => new Date().toISOString()
+} = {}) {
+  const current = normalizeSddState(state?.sdd);
+  const managed = new Map(current.files.map((file) => [file.destinationPath, { ...file }]));
+  const receiptFiles = new Map((receipt?.files ?? []).map((file) => [file.destinationPath, file]));
+  const backups = new Map((receipt?.backups ?? []).map((entry) => [entry.path, entry]));
+
+  for (const action of actions ?? []) {
+    if (!action?.ok || action.dryRun || action.action === "persona" || action.action === "skip") continue;
+    if (action.action === "delete") {
+      managed.delete(action.path);
+      continue;
+    }
+    if (action.action !== "restore") continue;
+    const file = receiptFiles.get(action.path);
+    const beforeHash = backups.get(action.path)?.beforeHash ?? file?.beforeHash ?? null;
+    if (beforeHash == null || !file) continue;
+    managed.set(action.path, {
+      destinationPath: action.path,
+      relativePath: file.relativePath ?? "SKILL.md",
+      skillId: file.skillId,
+      agentIds: [...(file.agentIds ?? [])],
+      hash: beforeHash,
+      skillHash: file.skillHash ?? null,
+      action: file.action
+    });
+  }
+
+  const files = [...managed.values()].sort((left, right) =>
+    left.destinationPath.localeCompare(right.destinationPath)
+  );
+  const personaAction = (actions ?? []).find((entry) => entry.action === "persona" && entry.ok);
+  let personaAgentIds = current.personaAgentIds;
+  if (files.length === 0 && !personaAction) personaAgentIds = [];
+  else if (personaAction) personaAgentIds = normalizePersonaAgentIds(personaAction.before ?? []);
+
+  return {
+    ...(state ?? {}),
+    sdd: {
+      ...current,
+      files,
+      agentIds: collectAgentIds(files),
+      personaAgentIds,
+      persona: derivePersona(personaAgentIds),
+      lastReceiptId: receipt?.id ?? current.lastReceiptId,
+      updatedAt: now()
+    }
+  };
+}

package/src/global/integrations/sdd-verify.js

@@ -0,0 +1,122 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { hashBuffer } from "../../hash.js";
+import { resolveAdapter } from "../registry.js";
+import { applySddConfigure } from "./sdd-apply.js";
+import { classifySddVerifyHealth, SDD_HEALTH } from "./sdd-evidence.js";
+import { harnessHomePaths } from "../paths.js";
+import {
+  SDD_SKILL_IDS,
+  groupSddSkillDestinations,
+  resolveSddAgentSelection
+} from "./sdd-destinations.js";
+import {
+  classifyPersonaHealth,
+  derivePersona,
+  normalizePersonaAgentIds,
+  SDD_PERSONA_GATE
+} from "./sdd-persona.js";
+import { compareSkillPaths, loadCanonicalSddSkill } from "./sdd-skill-files.js";
+
+/** Read-only verify: configured | missing | drifted | conflict (canonical vs disk). */
+export async function verifySddConfigure({
+  requestedAgentIds = null,
+  detectedAgentIds = [],
+  homeDir,
+  packageRoot,
+  trackedFiles = {},
+  personaAgentIds = [],
+  exists = existsSync,
+  readFileImpl = readFile
+} = {}) {
+  if (!homeDir) throw new Error("verifySddConfigure requires homeDir.");
+  if (!packageRoot) throw new Error("verifySddConfigure requires packageRoot.");
+
+  const agentIds = resolveSddAgentSelection({
+    requestedIds: requestedAgentIds,
+    detectedIds: detectedAgentIds
+  });
+  const groups = groupSddSkillDestinations(agentIds, homeDir);
+  const findings = [];
+
+  for (const skillId of SDD_SKILL_IDS) {
+    const { files, skillHash } = await loadCanonicalSddSkill(skillId, packageRoot);
+    for (const file of files) {
+      const canonicalHash = hashBuffer(file.bytes);
+      for (const group of groups) {
+        const destinationPath = join(group.root, skillId, ...file.relativePath.split("/"));
+        const fileExists = exists(destinationPath);
+        const diskHash = fileExists ? hashBuffer(await readFileImpl(destinationPath)) : null;
+        const trackedHash = trackedFiles[destinationPath] ?? null;
+        const health = classifySddVerifyHealth({
+          exists: fileExists, canonicalHash, diskHash, trackedHash
+        });
+        findings.push({
+          skillId, relativePath: file.relativePath, destinationPath,
+          agentIds: [...group.agentIds], kind: group.kind,
+          status: health.status, drift: health.drift, reason: health.reason,
+          canonicalHash, skillHash, diskHash, trackedHash
+        });
+      }
+    }
+  }
+
+  findings.sort((a, b) => compareSkillPaths(a.skillId, b.skillId)
+    || compareSkillPaths(a.relativePath, b.relativePath)
+    || compareSkillPaths(a.destinationPath, b.destinationPath));
+
+  const summary = { configured: 0, missing: 0, drifted: 0, conflict: 0 };
+  for (const entry of findings) summary[entry.status] += 1;
+
+  const consumers = normalizePersonaAgentIds(personaAgentIds);
+  const incompleteAgentIds = consumers.filter((id) => {
+    const mine = findings.filter((e) => e.agentIds.includes(id));
+    return !mine.length || mine.some((e) => e.status !== SDD_HEALTH.CONFIGURED);
+  });
+  let gatePresent = true;
+  for (const id of consumers) {
+    const p = join(homeDir, resolveAdapter(id).assets.configFile);
+    if (!exists(p) || !String(await readFileImpl(p, "utf8")).includes(SDD_PERSONA_GATE)) {
+      gatePresent = false;
+      break;
+    }
+  }
+  const personaHealth = classifyPersonaHealth({
+    personaAgentIds: consumers, gatePresent, incompleteAgentIds,
+    assetPresent: exists(join(harnessHomePaths(homeDir).root, "components/sdd-core/personas/teaching.md"))
+  });
+  return {
+    provider: "sdd-core", componentId: "sdd-core", agentIds, findings, summary,
+    status: summarizeSddHealth(summary),
+    ok: summary.missing === 0 && summary.drifted === 0 && summary.conflict === 0,
+    persona: {
+      ...personaHealth, persona: derivePersona(consumers), personaAgentIds: consumers, incompleteAgentIds
+    }
+  };
+}
+
+export function summarizeSddHealth(summary) {
+  if (summary.conflict > 0) return SDD_HEALTH.CONFLICT;
+  if (summary.missing > 0) return SDD_HEALTH.MISSING;
+  if (summary.drifted > 0) return SDD_HEALTH.DRIFTED;
+  return SDD_HEALTH.CONFIGURED;
+}
+
+/** Sync = verify then apply; conflicts block writes. */
+export async function syncSddConfigure(options = {}) {
+  const verification = await verifySddConfigure(options);
+  if (verification.summary.conflict > 0) {
+    return {
+      ...verification,
+      synced: false,
+      blocked: true,
+      applied: false,
+      cancelled: false,
+      receipt: null,
+      reason: "Conflicts present; refusing sync overwrite."
+    };
+  }
+  const result = await applySddConfigure(options);
+  return { ...result, verification, synced: Boolean(result.applied), blocked: false };
+}

package/src/global/intelligence/backends/opencode-catalog.js

@@ -0,0 +1,212 @@
+import {
+  COST_CLASSES,
+  OPENCODE_API_KEY_ENV,
+  PRIVACY_CLASSES,
+  TRANSPORT_KINDS,
+  createModelDescriptor
+} from "../types.js";
+import {
+  isDirectTransport,
+  normalizeModelId,
+  resolveOpencodeTransport
+} from "../transport-registry.js";
+import { fetchJson } from "../http.js";
+import { CAPABILITY_STATES } from "../../capability-states.js";
+import {
+  BILLING_MODELS,
+  ENTITLEMENT_STATES,
+  buildDirectEvidenceBase,
+  classifyModelsProbeStatus,
+  collectOpencodeCliEvidence
+} from "./opencode-evidence.js";
+
+export function resolveOpencodeApiKey({ env = process.env, apiKey = null } = {}) {
+  const value = apiKey ?? env[OPENCODE_API_KEY_ENV] ?? null;
+  if (value == null) return null;
+  const trimmed = String(value).trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+export function redactSecret(message, secret) {
+  if (!message || !secret) return message ?? null;
+  return String(message).split(String(secret)).join("[REDACTED]");
+}
+
+export function zenCostClassForModel(modelId) {
+  const id = normalizeModelId(modelId) ?? "";
+  return id === "big-pickle" || id.endsWith("-free") ? COST_CLASSES.FREE : COST_CLASSES.PAID;
+}
+
+export function goCostClassForModel() {
+  return COST_CLASSES.PAID;
+}
+
+/** Catalog/detection for OpenCode Go/Zen. Invoke composition ships in a later PR. */
+export function createOpencodeCatalogBackend({
+  id,
+  label,
+  product,
+  baseUrl,
+  defaultModelId,
+  costClassForModel,
+  env = process.env,
+  fetchImpl = globalThis.fetch,
+  apiKey = null,
+  collectCliEvidence = collectOpencodeCliEvidence
+}) {
+  const resolvedKey = resolveOpencodeApiKey({ env, apiKey });
+
+  return {
+    id,
+    label,
+    local: false,
+    product,
+    baseUrl,
+
+    async detect() {
+      const cliEvidence = collectCliEvidence({ env });
+      if (!resolvedKey) return missingKeyDetection(id, label, product, cliEvidence);
+
+      const probe = await fetchJson(`${baseUrl}/models`, {
+        headers: bearerHeaders(resolvedKey),
+        timeoutMs: 5000,
+        fetchImpl
+      });
+      const evidence = buildDirectEvidenceBase({
+        product,
+        hasApiKey: true,
+        cliEvidence,
+        modelsHttpStatus: probe.status || null,
+        modelsOk: probe.ok
+      });
+
+      if (!probe.ok) {
+        const entitlement = classifyModelsProbeStatus(probe.status);
+        return {
+          id,
+          label,
+          state: CAPABILITY_STATES.ERROR,
+          detected: true,
+          available: false,
+          hasApiKey: true,
+          cloud: true,
+          ...evidence,
+          entitlement,
+          error: redactSecret(probe.error ?? `HTTP ${probe.status}`, resolvedKey),
+          recommendation: describeAuthFailure(probe.status, label, product)
+        };
+      }
+
+      return {
+        id,
+        label,
+        state: CAPABILITY_STATES.AUTHENTICATED,
+        detected: true,
+        available: true,
+        hasApiKey: true,
+        cloud: true,
+        ...evidence,
+        error: null,
+        recommendation: `${label} HTTP authenticated via /models. Entitlement remains ${ENTITLEMENT_STATES.UNVERIFIED}; cloud invoke needs --cloud-consent --yes.`
+      };
+    },
+
+    async listModels() {
+      if (!resolvedKey) return [];
+      const result = await fetchJson(`${baseUrl}/models`, {
+        headers: bearerHeaders(resolvedKey),
+        timeoutMs: 10000,
+        fetchImpl
+      });
+      if (!result.ok) return [];
+
+      const mapped = [];
+      for (const remoteId of extractModelIds(result.data)) {
+        const modelId = normalizeModelId(remoteId);
+        const transport = resolveOpencodeTransport(product, modelId);
+        if (!isDirectTransport(transport)) continue;
+        mapped.push(createModelDescriptor({
+          provider: id,
+          modelId,
+          local: false,
+          costClass: costClassForModel(modelId),
+          privacyClass: PRIVACY_CLASSES.CLOUD,
+          transport
+        }));
+      }
+      return mapped;
+    },
+
+    async capabilities() {
+      const detection = await this.detect();
+      return {
+        id,
+        local: false,
+        cloud: true,
+        requiresApiKey: true,
+        requiresConsent: true,
+        streaming: false,
+        tools: false,
+        transports: [TRANSPORT_KINDS.CHAT_COMPLETIONS, TRANSPORT_KINDS.RESPONSES],
+        billingModel: detection.billingModel,
+        entitlement: detection.entitlement,
+        configured: detection.configured,
+        authenticated: detection.authenticated,
+        state: detection.state,
+        hasApiKey: Boolean(resolvedKey),
+        defaultModelId
+      };
+    }
+  };
+}
+
+function missingKeyDetection(id, label, product, cliEvidence = null) {
+  const evidence = buildDirectEvidenceBase({
+    product,
+    hasApiKey: false,
+    cliEvidence,
+    modelsHttpStatus: null,
+    modelsOk: false
+  });
+  const viaCli = evidence.configured;
+  return {
+    id,
+    label,
+    state: CAPABILITY_STATES.UNKNOWN,
+    detected: viaCli,
+    available: false,
+    hasApiKey: false,
+    cloud: true,
+    ...evidence,
+    error: null,
+    recommendation: viaCli
+      ? `${label} appears in OpenCode CLI auth list (${ENTITLEMENT_STATES.UNVERIFIED} entitlement). Intelligence direct HTTP still needs ${OPENCODE_API_KEY_ENV}, or use --backend opencode for CLI runtime.`
+      : `Set ${OPENCODE_API_KEY_ENV} for direct ${label} HTTP, or install/authenticate OpenCode CLI for runtime. Kairo never reads auth.json or claims balance without evidence.`
+  };
+}
+
+function bearerHeaders(apiKey) {
+  return { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" };
+}
+
+function extractModelIds(payload) {
+  const rows = Array.isArray(payload?.data)
+    ? payload.data
+    : Array.isArray(payload?.models)
+      ? payload.models
+      : Array.isArray(payload) ? payload : [];
+  return rows
+    .map((entry) => (typeof entry === "string" ? entry : entry?.id ?? entry?.name))
+    .filter(Boolean);
+}
+
+function describeAuthFailure(status, label, product = "zen") {
+  if (status === 401 || status === 403) {
+    return `${label} rejected the API key (HTTP ${status}). Key is configured but not authenticated for HTTP.`;
+  }
+  if (status === 429) {
+    return `${label} returned HTTP 429 (${ENTITLEMENT_STATES.LIMIT_REACHED}). Go limits do not automatically spend Zen credits.`;
+  }
+  const billing = product === "go" ? BILLING_MODELS.GO_PLAN : BILLING_MODELS.ZEN_CREDITS;
+  return `${label} model discovery failed (${billing} catalog; entitlement ${ENTITLEMENT_STATES.UNKNOWN}).`;
+}