@kal-elsam/kairo-runtime 0.11.0 → 0.13.0

package/src/global/observability/hermes-probe.js

@@ -0,0 +1,171 @@
+import { isAbsolute } from "node:path";
+import {
+  parseVersionFromOutput,
+  probeCommand as defaultProbeCommand
+} from "../cli-probe.js";
+import { normalizeProbeResult } from "./probe-contract.js";
+
+/** Surfaces recognized from `hermes --help` only — never executed by this probe. */
+export const HERMES_DIAGNOSTIC_SURFACES = Object.freeze(["version", "doctor", "status"]);
+export const HERMES_MANDATORY_SURFACES = Object.freeze(["version", "doctor"]);
+
+const WHICH_TIMEOUT_MS = 3000;
+const VERSION_TIMEOUT_MS = 8000;
+const HELP_TIMEOUT_MS = 8000;
+const MAX_PROBE_BYTES = 65_536;
+
+function result(partial) {
+  return normalizeProbeResult({
+    id: "hermes", version: null, contractCompatible: null,
+    diagnostics: [], evidence: [], error: null, ...partial
+  }, "hermes");
+}
+
+function boundText(raw, maxBytes = MAX_PROBE_BYTES) {
+  const text = String(raw ?? "");
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text;
+  return Buffer.from(text, "utf8").subarray(0, maxBytes).toString("utf8");
+}
+
+function whichAbsolutePath(command, env, run = defaultProbeCommand) {
+  const which = run("which", [command], { env, timeoutMs: WHICH_TIMEOUT_MS });
+  if (!which?.ok) return "";
+  const path = String(which.stdout ?? "").trim().split(/\r?\n/)[0] ?? "";
+  return isAbsolute(path) ? path : "";
+}
+
+/** Resolve absolute Hermes binary; never return a bare command name. */
+export function resolveHermesBinaryPath(command = "hermes", env = process.env, {
+  whichCommand,
+  probeCommand = defaultProbeCommand
+} = {}) {
+  const resolver = typeof whichCommand === "function"
+    ? whichCommand
+    : (cmd, e) => whichAbsolutePath(cmd, e, probeCommand);
+  const resolved = resolver(command, env) || null;
+  return resolved && isAbsolute(resolved) ? resolved : null;
+}
+
+/** Presence means the CLI *declares* the surface — not that Kairo may run it. */
+export function detectHermesDiagnosticSurfaces(helpText) {
+  const text = boundText(helpText);
+  const found = Object.create(null);
+  for (const name of HERMES_DIAGNOSTIC_SURFACES) {
+    found[name] = new RegExp(`(?:^|[\\s,{|/])${name}(?=[\\s,}|/-]|$)`, "m").test(text);
+  }
+  return Object.freeze(found);
+}
+
+function softError(label, kind, evidence, extra = {}) {
+  return result({
+    state: "error",
+    diagnostics: [`hermes ${label} ${kind === "timeout" ? "timed out" : "failed"}`],
+    error: kind === "timeout" ? "timeout" : kind === "exit" ? `exit ${extra.code}` : "spawn_error",
+    evidence,
+    ...extra.fields
+  });
+}
+
+function spawnFailure(label, probeResult, evidence, extra = {}) {
+  if (probeResult?.timedOut) return softError(label, "timeout", evidence, extra);
+  if (probeResult?.error) return softError(label, "spawn", evidence, extra);
+  if (probeResult?.status !== 0) {
+    return softError(label, "exit", evidence, { ...extra, code: probeResult?.status ?? "unknown" });
+  }
+  return null;
+}
+
+/** which: preserve timeout/spawn_error; exit/empty → missing (not failure). */
+function whichFailure(probeResult, evidence) {
+  if (probeResult?.timedOut) return softError("which", "timeout", evidence);
+  if (probeResult?.error) return softError("which", "spawn", evidence);
+  return null;
+}
+
+function runProbe(probeCommand, cmd, args, opts) {
+  try { return { ok: true, value: probeCommand(cmd, args, opts) }; }
+  catch { return { ok: false }; }
+}
+
+export async function probeHermes({
+  env = process.env,
+  cwd = process.cwd(),
+  whichCommand,
+  probeCommand = defaultProbeCommand
+} = {}) {
+  const noBinary = [{ kind: "binary", path: null }];
+  let path;
+
+  if (typeof whichCommand === "function") {
+    try { path = resolveHermesBinaryPath("hermes", env, { whichCommand, probeCommand }); }
+    catch { return softError("which", "spawn", noBinary); }
+  } else {
+    const inv = runProbe(probeCommand, "which", ["hermes"], { env, timeoutMs: WHICH_TIMEOUT_MS });
+    if (!inv.ok) return softError("which", "spawn", noBinary);
+    const fail = whichFailure(inv.value, noBinary);
+    if (fail) return fail;
+    const candidate = String(inv.value?.stdout ?? "").trim().split(/\r?\n/)[0] ?? "";
+    path = inv.value?.ok && isAbsolute(candidate) ? candidate : null;
+  }
+
+  if (!path) {
+    return result({
+      state: "missing",
+      diagnostics: [
+        "hermes absolute binary not resolved. Install Hermes Agent separately, then re-run the probe."
+      ],
+      evidence: noBinary
+    });
+  }
+
+  const evidence = [{ kind: "binary", path }];
+  const versionInv = runProbe(probeCommand, path, ["--version"], {
+    cwd, env, timeoutMs: VERSION_TIMEOUT_MS
+  });
+  if (!versionInv.ok) return softError("--version", "spawn", evidence);
+  const versionFail = spawnFailure("--version", versionInv.value, evidence);
+  if (versionFail) return versionFail;
+  const version = parseVersionFromOutput(boundText(versionInv.value.stdout));
+  evidence.push({ kind: "version", version, ok: true });
+  if (!version) {
+    return result({
+      state: "incompatible", contractCompatible: false, evidence,
+      diagnostics: ["hermes --version did not yield a parseable version"]
+    });
+  }
+
+  const helpInv = runProbe(probeCommand, path, ["--help"], {
+    cwd, env, timeoutMs: HELP_TIMEOUT_MS
+  });
+  if (!helpInv.ok) return softError("--help", "spawn", evidence, { fields: { version } });
+  const helpFail = spawnFailure("--help", helpInv.value, evidence, { fields: { version } });
+  if (helpFail) return helpFail;
+
+  const surfaces = detectHermesDiagnosticSurfaces(helpInv.value.stdout);
+  // Capability availability only — surfaces were not executed.
+  evidence.push({ kind: "diagnostic_surfaces", surfaces: { ...surfaces }, executed: false });
+
+  const missingMandatory = HERMES_MANDATORY_SURFACES.filter((name) => !surfaces[name]);
+  if (missingMandatory.length) {
+    return result({
+      state: "incompatible", version, contractCompatible: false, evidence,
+      diagnostics: missingMandatory.map((name) => `missing mandatory surface in --help: ${name}`)
+    });
+  }
+
+  return result({
+    state: "available", version, contractCompatible: true, evidence,
+    diagnostics: surfaces.status ? [] : ["optional surface absent in --help: status"]
+  });
+}
+
+export function createHermesProbe(deps = {}) {
+  return {
+    id: "hermes",
+    declaredEvents: Object.freeze([]),
+    declaredActions: Object.freeze([]),
+    async probe(context = {}) {
+      return probeHermes({ ...deps, ...context, env: context.env ?? deps.env ?? process.env });
+    }
+  };
+}

package/src/global/observability/index.js

@@ -0,0 +1,124 @@
+import { createGentleProbe } from "./gentle-probe.js";
+import { createGraphifyProbe } from "./graphify-probe.js";
+import { createHermesProbe } from "./hermes-probe.js";
+import { getObservabilityProbe, registerObservabilityProbe } from "./probe-registry.js";
+
+export {
+  OBSERVABILITY_PROBE_STATES,
+  assertObservabilityProbeContract,
+  normalizeProbeResult
+} from "./probe-contract.js";
+export {
+  registerObservabilityProbe,
+  getObservabilityProbe,
+  listObservabilityProbes,
+  resetObservabilityProbesForTests
+} from "./probe-registry.js";
+export { buildObservabilitySnapshot } from "./build-observability-snapshot.js";
+export {
+  PASSIVE_SNAPSHOT_TTL_MS,
+  PASSIVE_SNAPSHOT_MAX_ENTRIES,
+  buildPassiveSnapshotKey,
+  resetPassiveSnapshotFlightForTests,
+  passiveSnapshotInFlightSizeForTests,
+  runPassiveObservabilitySnapshot
+} from "./passive-snapshot-flight.js";
+export {
+  SUPPORTED_PROTOCOL, SUPPORTED_SCHEMA, SUPPORTED_CONTRACT,
+  SUPPORTED_MANDATORY_FEATURES, evaluateGentleCapabilities, probeGentle, createGentleProbe,
+  resolveGentleBinaryPath
+} from "./gentle-probe.js";
+export { exportGentleReviewBundle, resolveNegotiatedGentleBinary } from "./gentle-bundle-export.js";
+export { importGentleReviewBundle } from "./gentle-bundle-import.js";
+export {
+  inspectGraphArtifact, assertGraphInsideWorkspace,
+  resolveGraphifyBinaryPath, resolveGitHeadSha, scrubGitOverrideEnv,
+  probeGraphify, createGraphifyProbe
+} from "./graphify-probe.js";
+export {
+  GRAPHIFY_PARSE_TTL_MS,
+  GRAPHIFY_PARSE_MAX_ENTRIES,
+  buildGraphifyParseIdentity,
+  resetGraphifyParseCacheForTests,
+  inspectGraphArtifactCached
+} from "./graphify-parse-cache.js";
+export { runGraphifyOp, runGraphifyCli } from "./graphify-ops.js";
+export {
+  HERMES_DIAGNOSTIC_SURFACES, HERMES_MANDATORY_SURFACES,
+  detectHermesDiagnosticSurfaces, resolveHermesBinaryPath,
+  probeHermes, createHermesProbe
+} from "./hermes-probe.js";
+export {
+  DEFAULT_HERMES_API_URL,
+  HERMES_ACTIVITY_LIMIT_DEFAULT, HERMES_ACTIVITY_LIMIT_MAX,
+  HERMES_ACTIVITY_TIMEOUT_MS, HERMES_ACTIVE_WINDOW_MS,
+  assertHermesLoopbackUrl, capabilitiesAdvertiseSessionsList,
+  normalizeHermesSession, loadHermesActivity
+} from "./hermes-activity.js";
+export {
+  SYSTEM_RESOURCES_TIMEOUT_MS, PROCESS_ALLOWLIST,
+  parseProcessTable, loadSystemResources
+} from "./system-resources.js";
+export { recommendSystemResources } from "./resource-advisor.js";
+export {
+  ECOSYSTEM_UPDATES_CACHE_MS,
+  ECOSYSTEM_UPDATES_TIMEOUT_MS,
+  AGENT_SKILLS_PINNED_REV,
+  parseGentleUpdateOutput,
+  parseHermesUpdateCheck,
+  loadEcosystemUpdates
+} from "./ecosystem-updates.js";
+export {
+  KAIRO_VAULT_SUBDIR,
+  EXCLUDED_DIR_NAMES,
+  normalizeVaultPath,
+  isExcludedDirName,
+  isSecretBasename,
+  isAllowedKairoNoteName,
+  assertInsideKairoRoot,
+  resolveKairoNotePath,
+  inspectObsidianVault
+} from "./obsidian-vault.js";
+export {
+  formatKnowledgeFrontmatter,
+  renderDecisionMarkdown,
+  renderArchitectureMarkdown,
+  buildObsidianKnowledgePreview,
+  loadObsidianKnowledgePreview
+} from "./obsidian-knowledge-preview.js";
+export {
+  KAIRO_MANAGED_FRONTMATTER,
+  BACKUP_DIR_NAME,
+  hasConsent,
+  classifyNoteWrite,
+  planObsidianPublish,
+  publishObsidianProposals
+} from "./obsidian-publisher.js";
+export {
+  KAIRO_VIEW_KINDS,
+  parseKnowledgeFrontmatter,
+  extractWikilinks,
+  buildObsidianKnowledgeViews,
+  buildKnowledgeIndexProposals,
+  loadObsidianKnowledgeViews
+} from "./obsidian-knowledge-views.js";
+export {
+  emptyObsidianVaultStatus,
+  summarizeObsidianVaultStatus,
+  loadObsidianVaultStatus
+} from "./obsidian-status.js";
+export {
+  SOFT_LINK_WINDOW_MS,
+  parseCompanionTimestamp,
+  resolveRunTimestamp,
+  resolveReviewTimestamp,
+  softLinkReviewToRun,
+  summarizeCompanionProbes,
+  buildCompanionSnapshot
+} from "./build-companion-snapshot.js";
+
+export function ensureObservabilityProbesRegistered() {
+  if (!getObservabilityProbe("gentle")) registerObservabilityProbe(createGentleProbe());
+  if (!getObservabilityProbe("graphify")) registerObservabilityProbe(createGraphifyProbe());
+  if (!getObservabilityProbe("hermes")) registerObservabilityProbe(createHermesProbe());
+}

package/src/global/observability/obsidian-knowledge-preview.js

@@ -0,0 +1,214 @@
+import { resolveKairoNotePath } from "./obsidian-vault.js";
+
+const MAX_PROPOSALS = 40;
+const TITLE_MAX = 80;
+
+function envelope(partial = {}) {
+  return {
+    state: "error",
+    proposals: [],
+    diagnostics: [],
+    error: null,
+    generatedAt: null,
+    ...partial
+  };
+}
+
+function scrubTitle(raw, fallback = "untitled") {
+  const text = String(raw ?? "")
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/[\[\]#|\\/]+/g, " ")
+    .trim()
+    .slice(0, TITLE_MAX);
+  return text || fallback;
+}
+
+function slugify(title) {
+  return scrubTitle(title, "note")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48) || "note";
+}
+
+/** Stable YAML-ish frontmatter — no nested objects; values are scalars only. */
+export function formatKnowledgeFrontmatter(fields = {}) {
+  const lines = ["---"];
+  for (const key of Object.keys(fields).sort()) {
+    const value = fields[key];
+    if (value == null || value === "") continue;
+    const safe = String(value).replace(/[\r\n]+/g, " ").replace(/"/g, "'");
+    lines.push(`${key}: "${safe}"`);
+  }
+  lines.push("---", "");
+  return lines.join("\n");
+}
+
+export function renderDecisionMarkdown(entry, { generatedAt } = {}) {
+  const title = scrubTitle(entry?.title ?? entry?.id, "decision");
+  const id = scrubTitle(entry?.id ?? slugify(title), slugify(title));
+  const body = String(entry?.body ?? entry?.content ?? "").trim();
+  const fm = formatKnowledgeFrontmatter({
+    kairo_kind: "decision",
+    kairo_id: id,
+    source: "engram-export",
+    generated_at: generatedAt ?? null,
+    title
+  });
+  const wiki = `[[decisions/${slugify(title)}]]`;
+  return {
+    relativePath: `decisions/${slugify(title)}.md`,
+    title,
+    provenance: { system: "engram", kind: "decision", id },
+    markdown: `${fm}# ${title}\n\n${body || "_No body provided._"}\n\n---\nSource: Engram export · ${wiki}\n`
+  };
+}
+
+export function renderArchitectureMarkdown(entry, { generatedAt } = {}) {
+  const title = scrubTitle(entry?.title ?? entry?.name ?? entry?.id, "architecture");
+  const id = scrubTitle(entry?.id ?? slugify(title), slugify(title));
+  const detail = String(entry?.detail ?? entry?.summary ?? "").trim();
+  const links = Array.isArray(entry?.related)
+    ? entry.related.map((r) => `- [[architecture/${slugify(r)}]]`).join("\n")
+    : "";
+  const fm = formatKnowledgeFrontmatter({
+    kairo_kind: "architecture",
+    kairo_id: id,
+    source: "graphify-export",
+    generated_at: generatedAt ?? null,
+    title
+  });
+  return {
+    relativePath: `architecture/${slugify(title)}.md`,
+    title,
+    provenance: { system: "graphify", kind: "architecture", id },
+    markdown: `${fm}# ${title}\n\n${detail || "_No summary provided._"}\n${links ? `\n## Related\n${links}\n` : ""}`
+  };
+}
+
+/**
+ * Pure composer — accepts already-exported records only.
+ * Never opens Engram/Graphify internal DBs or vault files.
+ */
+export function buildObsidianKnowledgePreview({
+  decisions = [],
+  architecture = [],
+  generatedAt = new Date().toISOString(),
+  maxProposals = MAX_PROPOSALS,
+  kairoRoot = "/virtual/Kairo"
+} = {}) {
+  const diagnostics = [];
+  const proposals = [];
+
+  const push = (draft) => {
+    if (proposals.length >= maxProposals) return;
+    const gate = resolveKairoNotePath(kairoRoot, draft.relativePath);
+    if (!gate.ok) {
+      diagnostics.push(`rejected ${draft.relativePath}: ${gate.reason}`);
+      return;
+    }
+    proposals.push({
+      relativePath: draft.relativePath,
+      title: draft.title,
+      markdown: draft.markdown,
+      provenance: draft.provenance,
+      absolutePath: gate.path
+    });
+  };
+
+  for (const entry of decisions ?? []) {
+    if (entry == null || typeof entry !== "object") {
+      diagnostics.push("skipped malformed decision");
+      continue;
+    }
+    push(renderDecisionMarkdown(entry, { generatedAt }));
+  }
+  for (const entry of architecture ?? []) {
+    if (entry == null || typeof entry !== "object") {
+      diagnostics.push("skipped malformed architecture");
+      continue;
+    }
+    push(renderArchitectureMarkdown(entry, { generatedAt }));
+  }
+
+  if (proposals.length === 0 && diagnostics.length === 0) {
+    return envelope({
+      state: "empty",
+      proposals: [],
+      diagnostics: ["no export records provided"],
+      generatedAt,
+      error: null
+    });
+  }
+
+  return envelope({
+    state: proposals.length > 0 ? "available" : "partial",
+    proposals,
+    diagnostics,
+    generatedAt,
+    error: null
+  });
+}
+
+/**
+ * Load preview via injectable export adapters — never vault writes.
+ * Adapters must return plain arrays of records (already exported).
+ */
+export async function loadObsidianKnowledgePreview({
+  loadEngramExport = null,
+  loadGraphifyExport = null,
+  kairoRoot = "/virtual/Kairo",
+  generatedAt = new Date().toISOString(),
+  maxProposals = MAX_PROPOSALS
+} = {}) {
+  const diagnostics = [];
+  let decisions = [];
+  let architecture = [];
+
+  if (typeof loadEngramExport === "function") {
+    try {
+      const raw = await loadEngramExport();
+      decisions = Array.isArray(raw) ? raw : Array.isArray(raw?.decisions) ? raw.decisions : [];
+      if (!Array.isArray(raw) && raw != null && !Array.isArray(raw?.decisions)) {
+        diagnostics.push("engram export shape unrecognized");
+      }
+    } catch (err) {
+      diagnostics.push(`engram export failed: ${String(err?.message ?? err)}`);
+    }
+  } else {
+    diagnostics.push("engram export adapter not provided");
+  }
+
+  if (typeof loadGraphifyExport === "function") {
+    try {
+      const raw = await loadGraphifyExport();
+      architecture = Array.isArray(raw)
+        ? raw
+        : Array.isArray(raw?.architecture)
+          ? raw.architecture
+          : Array.isArray(raw?.communities)
+            ? raw.communities
+            : [];
+      if (
+        !Array.isArray(raw)
+        && raw != null
+        && !Array.isArray(raw?.architecture)
+        && !Array.isArray(raw?.communities)
+      ) {
+        diagnostics.push("graphify export shape unrecognized");
+      }
+    } catch (err) {
+      diagnostics.push(`graphify export failed: ${String(err?.message ?? err)}`);
+    }
+  } else {
+    diagnostics.push("graphify export adapter not provided");
+  }
+
+  const preview = buildObsidianKnowledgePreview({
+    decisions, architecture, generatedAt, maxProposals, kairoRoot
+  });
+  return {
+    ...preview,
+    diagnostics: [...diagnostics, ...(preview.diagnostics ?? [])]
+  };
+}