@kal-elsam/kairo-runtime 0.12.0 → 0.13.1

package/src/global/ink/ux/live-overview.js

@@ -2,10 +2,13 @@
  * Live semantic Overview for Cockpit HOME — product cover.
  * Nav owns the sole focus mark — this panel never renders `>`.
  * ASCII wordmark only here (wide/compact); minimal is textual.
+ *
+ * Rule: show purpose + one next step + a few plain-language needs.
+ * Machine/system noise stays out of the first screen (Details only).
  */
 import React from "react";
 import { Box, Text } from "ink";
-import { CONTROL_PLANE_HEALTH } from "../../control-plane-snapshot.js";
+import { DASHBOARD_PURPOSE } from "../../dashboard-guidance.js";
 import { LAYOUT_MODES } from "../layout.js";
 import { COCKPIT_COLORS } from "../theme.js";
 import {
@@ -14,86 +17,95 @@ import {
   wordmarkLines
 } from "../brand/wordmark.js";
 import { ActionList, Callout, Details } from "./semantic.js";
+import {
+  humanizeDestination,
+  humanizeHealthTitle,
+  humanizePrimary,
+  mapHealthTone,
+  partitionCompanionLines
+} from "./overview-needs.js";
 
-const DESTINATION_LABELS = {
-  setup: "Setup",
-  changes: "Governance",
-  ides: "Agents",
-  runs: "Orchestration",
-  "control-center": "Overview",
-  activity: "Activity",
-  usage: "Usage",
-  profile: "Settings"
-};
-
-export function mapHealthTone(kind) {
-  switch (kind) {
-    case CONTROL_PLANE_HEALTH.CHECK_FAILED:
-      return "danger";
-    case CONTROL_PLANE_HEALTH.ACTION_REQUIRED:
-    case CONTROL_PLANE_HEALTH.NOT_CONFIGURED:
-    case CONTROL_PLANE_HEALTH.HEALTHY_WITH_NOTES:
-      return "warn";
-    case CONTROL_PLANE_HEALTH.HEALTHY:
-      return "ready";
-    default:
-      return "warn";
-  }
-}
-
-function humanizeDestination(destination) {
-  if (!destination) return null;
-  return DESTINATION_LABELS[destination] ?? null;
-}
+export {
+  humanizeCompanionNeed,
+  humanizeHealthTitle,
+  humanizePrimary,
+  mapHealthTone,
+  partitionCompanionLines
+} from "./overview-needs.js";
 
-/** Safe Details lines only — never invent paths/IDs; honest empty when none. */
-export function buildOverviewDetails(model = {}) {
+/** Safe Details lines — leftovers + raw signals; never invent paths/IDs. */
+export function buildOverviewDetails(model = {}, companionRest = []) {
   const lines = [];
   const next = model.nextAction ?? model.cta ?? {};
   const dest = humanizeDestination(next.destination);
-  if (dest) lines.push(`Next destination · ${dest}`);
-  if (typeof model.alerts?.count === "number") {
+  if (dest) lines.push(`Opens · ${dest}`);
+  if (typeof model.alerts?.count === "number" && model.alerts.count > 0) {
     lines.push(`Open alerts · ${model.alerts.count}`);
   }
+  const tokens = model.tokens?.headline;
+  if (typeof tokens === "string" && tokens && !/unavailable/i.test(tokens)) {
+    lines.push(`Tokens · ${tokens}`);
+  }
   const secondary = model.companionNextAction;
   if (secondary?.title && secondary.kind !== "idle") {
     lines.push(`Companion · ${secondary.title}`);
   }
-  if (lines.length === 0) return ["No extra evidence beyond the metrics above."];
+  for (const line of companionRest) {
+    if (typeof line === "string" && line.trim()) lines.push(line);
+  }
+  if (lines.length === 0) return ["Nothing else to show right now."];
   return lines;
 }
 
 /**
  * Pure adapter: buildControlCenterModel → semantic overview props.
- * Callout / CTA / metrics never include paths or IDs.
- * Primary action is always governance CTA — companion is secondary metrics/details only.
+ * First screen = purpose + next step + plain needs. Machine noise → Details.
  */
 export function adaptControlCenterToOverview(model = {}) {
   const status = model.status ?? model.health ?? {};
   const next = model.nextAction ?? model.cta ?? {};
-  const companionMetrics = (model.companion?.lines ?? []).map((label, i) => ({
-    id: `companion-${i}`,
-    label
-  }));
+  const { needs, rest } = partitionCompanionLines(model.companion?.lines ?? []);
+  const primary = humanizePrimary(next);
+
+  const activity = model.activity?.headline;
+  const metrics = [];
+  const hasUsefulActivity = typeof activity === "string"
+    && activity
+    && activity !== "Idle"
+    && activity !== "No activity yet";
+  if (hasUsefulActivity) {
+    metrics.push({ id: "activity", label: `Last activity · ${activity.replace(/^Last ·\s*/, "")}` });
+  }
+  for (let i = 0; i < needs.length; i += 1) {
+    metrics.push({ id: `need-${i}`, label: needs[i] });
+  }
+  if ((model.alerts?.count ?? 0) > 0) {
+    metrics.push({
+      id: "alerts",
+      label: `Alerts · ${model.alerts.headline ?? `${model.alerts.count} open`}`
+    });
+  }
+  if (rest.length > 0) {
+    metrics.push({
+      id: "more",
+      label: `${rest.length} more in Details · Space`
+    });
+  }
+  if (metrics.length === 0) {
+    metrics.push({ id: "quiet", label: "Nothing else needs you right now" });
+  }
+
   return {
     title: model.title ?? "Overview",
+    purpose: DASHBOARD_PURPOSE,
     callout: {
       tone: mapHealthTone(status.kind),
-      title: status.label ?? "Unknown",
+      title: humanizeHealthTitle(status.kind, status.label),
       body: status.summaryLine ?? ""
     },
-    primary: {
-      label: next.actionTitle ?? "Review control plane",
-      detail: next.actionDetail || null,
-      hint: next.enterHint ?? null
-    },
-    metrics: [
-      { id: "activity", label: `Activity · ${model.activity?.headline ?? "Idle"}` },
-      { id: "alerts", label: `Alerts · ${model.alerts?.headline ?? "Alert data unavailable"}` },
-      { id: "tokens", label: `Tokens · ${model.tokens?.headline ?? "Data unavailable"}` },
-      ...companionMetrics
-    ],
-    details: buildOverviewDetails(model)
+    primary,
+    metrics,
+    details: buildOverviewDetails(model, rest)
   };
 }
 
@@ -150,11 +162,14 @@ export function SemanticOverviewPanel({
 
   return React.createElement(Box, { flexDirection: "column" },
     hero,
+    React.createElement(Text, {
+      color: colorEnabled ? COCKPIT_COLORS.muted : undefined
+    }, view.purpose),
     React.createElement(Box, { marginTop: 1, flexDirection: "column" },
       React.createElement(Text, {
         bold: true,
         color: colorEnabled ? COCKPIT_COLORS.interactive : undefined
-      }, view.primary.label),
+      }, `→ ${view.primary.label}`),
       view.primary.detail
         ? React.createElement(Text, null, view.primary.detail)
         : null,
@@ -175,7 +190,7 @@ export function SemanticOverviewPanel({
     ),
     React.createElement(Details, {
       open: detailsOpen,
-      summary: "Details",
+      summary: "More info",
       lines: view.details,
       colorEnabled,
       focused: false,

package/src/global/ink/ux/overview-needs.js

@@ -0,0 +1,160 @@
+/**
+ * Plain-language Overview needs — no machine noise on the first screen.
+ */
+import { CONTROL_PLANE_HEALTH } from "../../control-plane-snapshot.js";
+import { formatCliCommand } from "../../brand/cli.js";
+
+export const OVERVIEW_NEED_LIMIT = 3;
+
+/** Prefixes that never belong on the first screen (machine / internals). */
+export const DETAILS_ONLY_PREFIXES = [
+  "System",
+  "Advisor",
+  "Soft links",
+  "Gentle",
+  "Graphify",
+  "Hermes"
+];
+
+const DESTINATION_LABELS = {
+  setup: "Setup",
+  changes: "Governance",
+  ides: "Agents",
+  runs: "Orchestration",
+  "control-center": "Overview",
+  activity: "Activity",
+  usage: "Usage",
+  profile: "Settings"
+};
+
+export function mapHealthTone(kind) {
+  switch (kind) {
+    case CONTROL_PLANE_HEALTH.CHECK_FAILED:
+      return "danger";
+    case CONTROL_PLANE_HEALTH.ACTION_REQUIRED:
+    case CONTROL_PLANE_HEALTH.NOT_CONFIGURED:
+    case CONTROL_PLANE_HEALTH.HEALTHY_WITH_NOTES:
+      return "warn";
+    case CONTROL_PLANE_HEALTH.HEALTHY:
+      return "ready";
+    default:
+      return "warn";
+  }
+}
+
+/** Plain-language status title — never shouty ALL-CAPS jargon alone. */
+export function humanizeHealthTitle(kind, fallback = "Unknown") {
+  switch (kind) {
+    case CONTROL_PLANE_HEALTH.NOT_CONFIGURED:
+      return "Needs setup";
+    case CONTROL_PLANE_HEALTH.ACTION_REQUIRED:
+      return "Needs attention";
+    case CONTROL_PLANE_HEALTH.CHECK_FAILED:
+      return "Something failed";
+    case CONTROL_PLANE_HEALTH.HEALTHY_WITH_NOTES:
+      return "Ready · with notes";
+    case CONTROL_PLANE_HEALTH.HEALTHY:
+      return "Ready";
+    default:
+      return typeof fallback === "string" && fallback ? fallback : "Unknown";
+  }
+}
+
+export function humanizeDestination(destination) {
+  if (!destination) return null;
+  return DESTINATION_LABELS[destination] ?? null;
+}
+
+/**
+ * Turn a raw companion line into a user-facing need, or null to skip.
+ * System/machine lines are never returned here.
+ */
+export function humanizeCompanionNeed(line) {
+  if (typeof line !== "string" || line.trim().length === 0) return null;
+  if (/^\s/.test(line)) return null;
+
+  for (const prefix of DETAILS_ONLY_PREFIXES) {
+    if (line.startsWith(prefix)) return null;
+  }
+
+  if (line.startsWith("Obsidian · unconfigured")) {
+    return "Obsidian not connected · open Settings to choose your vault";
+  }
+  if (line.startsWith("Obsidian · missing")) {
+    return "Obsidian vault folder missing · check Settings";
+  }
+  if (line.startsWith("Obsidian · unavailable") || line.startsWith("Obsidian · error")) {
+    return "Obsidian unavailable · check Settings";
+  }
+  if (/^Updates · \d+\s+available/i.test(line)) {
+    return `Update available · run ${formatCliCommand("updates check")}`;
+  }
+  if (line.startsWith("Engram · conflict")) {
+    return "Memory conflict · open Settings → Engram";
+  }
+  if (line.startsWith("Engram · missing") || line.startsWith("Engram · error")) {
+    return "Memory not ready · open Settings → Engram";
+  }
+  return null;
+}
+
+/** Partition companion lines: plain needs for Overview, raw rest for Details. */
+export function partitionCompanionLines(lines = []) {
+  const needs = [];
+  const rest = [];
+  for (const line of lines) {
+    if (typeof line !== "string" || line.trim().length === 0) continue;
+    const need = humanizeCompanionNeed(line);
+    if (need && needs.length < OVERVIEW_NEED_LIMIT) {
+      needs.push(need);
+      continue;
+    }
+    rest.push(line);
+  }
+  return { needs, rest };
+}
+
+export function humanizePrimary(next = {}) {
+  const kind = next.kind;
+  const detail = typeof next.actionDetail === "string" && next.actionDetail.trim()
+    ? next.actionDetail.trim()
+    : null;
+  switch (kind) {
+    case "setup":
+      return {
+        label: "Start setup",
+        detail: detail ?? `Run ${formatCliCommand("setup")} to configure agents for this project.`,
+        hint: "Enter → open Setup"
+      };
+    case "repair":
+      return {
+        label: "Fix drift",
+        detail: detail ?? `Run ${formatCliCommand("sync")} to repair managed content.`,
+        hint: "Enter → preview in Governance"
+      };
+    case "verify":
+      return {
+        label: "Check what failed",
+        detail: detail ?? `Run ${formatCliCommand("doctor")} for details.`,
+        hint: "Enter → reload"
+      };
+    case "review":
+      return {
+        label: "Review notes",
+        detail: detail ?? "Open Governance to inspect remaining notes.",
+        hint: "Enter → open"
+      };
+    case "idle":
+      return {
+        label: "All clear",
+        detail: detail ?? "No action needed right now.",
+        hint: null
+      };
+    default:
+      return {
+        label: next.actionTitle ?? "Review control plane",
+        detail,
+        hint: next.enterHint ?? "Enter →"
+      };
+  }
+}

package/src/global/observability/build-companion-snapshot.js

@@ -7,6 +7,11 @@ import { loadHermesActivity as defaultHermesActivity } from "./hermes-activity.j
 import { loadSystemResources as defaultSystemResources } from "./system-resources.js";
 import { recommendSystemResources } from "./resource-advisor.js";
 import { loadEcosystemUpdates as defaultEcosystemUpdates } from "./ecosystem-updates.js";
+import {
+  emptyObsidianVaultStatus,
+  loadObsidianVaultStatus as defaultObsidianVault,
+  summarizeObsidianVaultStatus
+} from "./obsidian-status.js";
 import { getObservabilityProbe, registerObservabilityProbe } from "./probe-registry.js";
 
 export const SOFT_LINK_WINDOW_MS = 60 * 60 * 1000;
@@ -179,7 +184,8 @@ function emptyCompanion(error = null) {
       graphify: { state: "error", error: null, diagnostics: [], graphStatus: null },
       hermes: { activity: emptyHermesActivity() },
       system: { resources: emptySystemResources(), advice: { recommendations: [], deepScan: false } },
-      ecosystem: { updates: emptyEcosystemUpdates() }
+      ecosystem: { updates: emptyEcosystemUpdates() },
+      obsidian: { vault: emptyObsidianVaultStatus() }
     },
     engram: { status: "error", binary: null },
     links: [], alertsCount: null,
@@ -199,6 +205,7 @@ export async function buildCompanionSnapshot({
   loadHermesActivity = defaultHermesActivity,
   loadSystemResources = defaultSystemResources,
   loadEcosystemUpdates = defaultEcosystemUpdates,
+  loadObsidianVaultStatus = defaultObsidianVault,
   resourceDeepScan = false,
   observabilityContext = {}
 } = {}) {
@@ -249,6 +256,19 @@ export async function buildCompanionSnapshot({
       ecosystemUpdates = emptyEcosystemUpdates();
     }
 
+    let obsidianVault = emptyObsidianVaultStatus();
+    try {
+      obsidianVault = summarizeObsidianVaultStatus(
+        await loadObsidianVaultStatus({
+          vaultPath: observabilityContext?.obsidianVaultPath ?? observabilityContext?.vaultPath ?? null,
+          lastPublishAt: observabilityContext?.obsidianLastPublishAt ?? null,
+          pendingProposals: observabilityContext?.obsidianPendingProposals ?? 0
+        })
+      );
+    } catch {
+      obsidianVault = emptyObsidianVaultStatus();
+    }
+
     const reviewList = Array.isArray(reviews)
       ? reviews
       : (typeof loadReviews === "function" ? await loadReviews() : []);
@@ -259,7 +279,8 @@ export async function buildCompanionSnapshot({
       ...summarizeCompanionProbes(obs?.probes ?? []),
       hermes: { activity: hermesActivity },
       system: { resources: systemResources, advice: systemAdvice },
-      ecosystem: { updates: ecosystemUpdates }
+      ecosystem: { updates: ecosystemUpdates },
+      obsidian: { vault: obsidianVault }
     };
     const links = [];
     for (const review of reviewList ?? []) {

package/src/global/observability/index.js

@@ -68,6 +68,45 @@ export {
   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,

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 ?? [])]
+  };
+}