@kal-elsam/kairo-runtime 0.11.0 → 0.12.0

package/src/global/mcp/kairo-mcp.js

@@ -0,0 +1,230 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import * as z from "zod";
+import { resolveHomeDir } from "../paths.js";
+import { buildControlPlaneSnapshot } from "../control-plane-snapshot.js";
+import { listRunRecords } from "../runtime/run-store.js";
+import { listAlerts } from "../runtime/alerts/alert-store.js";
+import { listReviewReceipts } from "../runtime/review/review-receipts.js";
+import { buildCompanionSnapshot } from "../observability/build-companion-snapshot.js";
+import { probeGentle } from "../observability/gentle-probe.js";
+import { runGraphifyOp } from "../observability/graphify-ops.js";
+import { resolveGitHeadSha } from "../observability/graphify-probe.js";
+import { runPassiveObservabilitySnapshot } from "../observability/passive-snapshot-flight.js";
+import { inspectEngramIntegration } from "../integrations/engram-evidence.js";
+
+export const KAIRO_MCP_TOOLS = Object.freeze([
+  "kairo_status", "kairo_runs", "kairo_alerts", "kairo_gentle_status",
+  "kairo_graph_query", "kairo_graph_path", "kairo_context_summary"
+]);
+
+const empty = z.object({});
+export const mcpSchemas = Object.freeze({
+  empty,
+  runs: z.object({ limit: z.number().int().min(1).max(20).default(20), activeOnly: z.boolean().optional() }),
+  alerts: z.object({
+    limit: z.number().int().min(1).max(50).default(50),
+    state: z.enum(["open", "resolved", "dismissed"]).optional()
+  }),
+  graphQuery: z.object({
+    graph: z.string().min(1), question: z.string().min(1),
+    budget: z.number().int().min(1).max(8000).default(2000)
+  }),
+  graphPath: z.object({ graph: z.string().min(1), from: z.string().min(1), to: z.string().min(1) })
+});
+
+const CODE_RE = /^(?:[a-z][a-z0-9_]{0,48}|status=\d+)$/;
+export const pubCodes = (xs = []) => xs.map(String).filter((d) => CODE_RE.test(d));
+
+export function mcpResult({ ok, code, data = null, diagnostics = [], isError = false }) {
+  const structuredContent = { ok, code, data, diagnostics: pubCodes(diagnostics) };
+  return {
+    content: [{ type: "text", text: JSON.stringify(structuredContent) }],
+    structuredContent, ...(isError ? { isError: true } : {})
+  };
+}
+
+const pubRun = (r) => ({
+  runId: r?.runId ?? null, state: r?.state ?? null, agentId: r?.agentId ?? null,
+  startedAt: r?.startedAt ?? null, updatedAt: r?.updatedAt ?? null,
+  endedAt: r?.endedAt ?? r?.completedAt ?? null
+});
+const pubAlert = (a) => ({
+  alertId: a?.alertId ?? null, state: a?.state ?? null, kind: a?.kind ?? null,
+  severity: a?.severity ?? null, title: a?.title ?? null, createdAt: a?.createdAt ?? null
+});
+export const pubCoverage = (c) => (c == null ? null : {
+  detectedAgents: Number(c.detectedAgents) || 0, governedAgents: Number(c.governedAgents) || 0,
+  components: Number(c.components) || 0,
+  activeModules: Array.isArray(c.activeModules) ? c.activeModules.map(String) : []
+});
+export const pubGentle = (p) => ({
+  state: p?.state ?? "missing", error: null,
+  diagnostics: (p?.state === "error") ? ["provider_error"] : pubCodes(p?.diagnostics)
+});
+export const pubSignals = (s) => ({
+  gentle: { state: s?.gentle?.state ?? "missing", error: null, diagnostics: [] },
+  graphify: {
+    state: s?.graphify?.state ?? "missing", error: null, diagnostics: [],
+    graphStatus: s?.graphify?.graphStatus ?? null
+  }
+});
+export const pubEngram = (e) => ({ status: e?.status ?? "missing", binary: null, error: null });
+const pubNext = (n) => (n == null ? null : { kind: n.kind ?? null, displayOnly: true, secondary: true });
+const pubCompanion = (c) => ({
+  ok: Boolean(c?.ok), signals: pubSignals(c?.signals), engram: pubEngram(c?.engram),
+  nextSafeAction: pubNext(c?.nextSafeAction), alertsCount: c?.alertsCount ?? null,
+  linksCount: c?.links?.length ?? 0
+});
+const pubLinks = (links) => (links ?? []).map((l) => ({
+  kind: "soft", displayOnly: true, agentId: l.agentId ?? null,
+  reviewId: l.reviewId ?? null, runId: l.runId ?? null, deltaMs: l.deltaMs ?? null
+}));
+
+function graphEnvelope(result) {
+  return mcpResult({
+    ok: Boolean(result.ok), code: result.ok ? "ok" : (result.code ?? "graphify_error"),
+    data: {
+      op: result.op ?? null, text: result.ok ? (result.text ?? null) : null, truncated: Boolean(result.truncated),
+      graphPath: result.graphPath ?? null, graphStatus: result.graphStatus ?? null
+    },
+    diagnostics: result.diagnostics ?? [], isError: !result.ok
+  });
+}
+
+export function createToolHandlers(deps = {}) {
+  const homeDir = deps.homeDir ?? resolveHomeDir();
+  const cwd = deps.cwd ?? process.cwd();
+  const listRuns = deps.listRuns ?? ((o) => listRunRecords(homeDir, o));
+  const listAlertRows = deps.listAlerts ?? ((o) => listAlerts({ homeDir, ...o }));
+  const listReviews = deps.listReviews ?? (() => listReviewReceipts({ homeDir, limit: 20 }));
+  const buildStatus = deps.buildStatus ?? (() => buildControlPlaneSnapshot({
+    homeDir, workspaceRoot: cwd, packageRoot: deps.packageRoot, packageName: deps.packageName,
+    cliVersion: deps.version, includeDiff: false, includeExplain: false, includeRuntime: true
+  }));
+  const resolveHead = deps.resolveHead ?? ((dir) => resolveGitHeadSha(dir));
+  /** Fresh HEAD per request/snapshot — never cache across MCP tool calls. */
+  const requestHead = () => resolveHead(cwd);
+  const buildObs = deps.buildObservability
+    ?? ((ctx) => runPassiveObservabilitySnapshot(ctx, { force: Boolean(ctx?.force) }));
+  const buildCompanion = deps.buildCompanion ?? ((ctx) => buildCompanionSnapshot({
+    ...ctx,
+    inspectEngram: deps.inspectEngram ?? ((c) => inspectEngramIntegration(c)),
+    loadAlerts: async () => listAlertRows({ limit: 50 }),
+    loadReviews: async () => listReviews(),
+    buildObservability: buildObs,
+    ensureRegistered: deps.ensureRegistered,
+    observabilityContext: { cwd, homeDir, workspaceRoot: cwd, headSha: requestHead() }
+  }));
+  const gentleProbe = deps.probeGentle ?? ((ctx) => probeGentle(ctx));
+  const graphOp = deps.runGraphifyOp ?? runGraphifyOp;
+  const gOpts = () => ({
+    cwd, workspaceRoot: cwd, headSha: requestHead(), whichCommand: deps.whichCommand,
+    probeCommand: deps.probeCommand, containPath: deps.containPath,
+    inspectGraph: deps.inspectGraph, resolveHead
+  });
+  const soft = (code, data) => mcpResult({
+    ok: true, code, data,
+    diagnostics: code === "degraded" ? [`${Object.keys(data)[0]}_unavailable`] : []
+  });
+  const graphFail = () => mcpResult({
+    ok: false, code: "provider_error", data: null, diagnostics: ["provider_error"], isError: true
+  });
+
+  return {
+    async kairo_status() {
+      try {
+        const snap = await buildStatus();
+        const runs = await listRuns({ limit: 20, activeOnly: false }).catch(() => []);
+        const companion = await buildCompanion({ controlPlaneHealth: snap?.health ?? null, runs });
+        return mcpResult({
+          ok: true, code: "ok",
+          data: {
+            health: snap?.health ?? null, coverage: pubCoverage(snap?.coverage),
+            cta: snap?.cta ? { kind: snap.cta.kind ?? null } : null,
+            companion: pubCompanion(companion)
+          }
+        });
+      } catch { return soft("degraded", { health: null, coverage: null, companion: null }); }
+    },
+    async kairo_runs({ limit = 20, activeOnly = false } = {}) {
+      try {
+        return mcpResult({ ok: true, code: "ok", data: { runs: (await listRuns({ limit, activeOnly: Boolean(activeOnly) })).map(pubRun) } });
+      } catch { return soft("degraded", { runs: [] }); }
+    },
+    async kairo_alerts({ limit = 50, state } = {}) {
+      try {
+        return mcpResult({ ok: true, code: "ok", data: { alerts: (await listAlertRows({ limit, state: state ?? null })).map(pubAlert) } });
+      } catch { return soft("degraded", { alerts: [] }); }
+    },
+    async kairo_gentle_status() {
+      try {
+        const probe = pubGentle(await gentleProbe({ cwd, homeDir, workspaceRoot: cwd }));
+        return mcpResult({
+          ok: true, code: probe.state === "available" ? "ok" : "degraded", data: probe,
+          diagnostics: probe.state === "missing" ? ["gentle_missing"] : []
+        });
+      } catch {
+        return mcpResult({
+          ok: true, code: "degraded", data: { state: "missing", error: null, diagnostics: [] },
+          diagnostics: ["gentle_unavailable"]
+        });
+      }
+    },
+    async kairo_graph_query({ graph, question, budget = 2000 }) {
+      try {
+        return graphEnvelope(await graphOp({
+          op: "query", args: [question], graphPath: graph, budget, ...gOpts()
+        }));
+      } catch { return graphFail(); }
+    },
+    async kairo_graph_path({ graph, from, to }) {
+      try {
+        return graphEnvelope(await graphOp({
+          op: "path", args: [from, to], graphPath: graph, ...gOpts()
+        }));
+      } catch { return graphFail(); }
+    },
+    async kairo_context_summary() {
+      try {
+        const companion = await buildCompanion({ runs: await listRuns({ limit: 20, activeOnly: false }) });
+        return mcpResult({
+          ok: true, code: companion?.ok === false ? "degraded" : "ok",
+          data: {
+            signals: pubSignals(companion?.signals), engram: pubEngram(companion?.engram),
+            links: pubLinks(companion?.links), alertsCount: companion?.alertsCount ?? null,
+            nextSafeAction: pubNext(companion?.nextSafeAction)
+          },
+          diagnostics: companion?.ok === false ? ["companion_degraded"] : []
+        });
+      } catch {
+        return soft("degraded", { signals: null, engram: null, links: [], alertsCount: null, nextSafeAction: null });
+      }
+    }
+  };
+}
+
+export function registerKairoMcpTools(registerTool, deps = {}) {
+  const h = createToolHandlers(deps);
+  for (const [name, description, inputSchema] of [
+    ["kairo_status", "Read-only control-plane + companion summary", empty],
+    ["kairo_runs", "Read-only run list", mcpSchemas.runs],
+    ["kairo_alerts", "Read-only alert list", mcpSchemas.alerts],
+    ["kairo_gentle_status", "Gentle probe / companion gentle signal", empty],
+    ["kairo_graph_query", "Read-only Graphify query", mcpSchemas.graphQuery],
+    ["kairo_graph_path", "Read-only Graphify path", mcpSchemas.graphPath],
+    ["kairo_context_summary", "Companion + soft links + alerts count", empty]
+  ]) registerTool(name, { description, inputSchema }, h[name]);
+  return h;
+}
+
+export function createKairoMcpServer(deps = {}) {
+  const Server = deps.McpServer ?? McpServer;
+  const server = new Server({ name: "kairo", version: deps.version ?? "0.11.0" });
+  registerKairoMcpTools(deps.registerTool ?? ((n, c, h) => server.registerTool(n, c, h)), deps);
+  return server;
+}
+
+export function runKairoMcp(deps = {}) {
+  return (deps.serveStdio ?? serveStdio)(() => createKairoMcpServer(deps));
+}

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

@@ -0,0 +1,281 @@
+import { CONTROL_PLANE_HEALTH } from "../control-plane-snapshot.js";
+import { buildObservabilitySnapshot as defaultObs } from "./build-observability-snapshot.js";
+import { createGentleProbe } from "./gentle-probe.js";
+import { createGraphifyProbe } from "./graphify-probe.js";
+import { createHermesProbe } from "./hermes-probe.js";
+import { loadHermesActivity as defaultHermesActivity } from "./hermes-activity.js";
+import { loadSystemResources as defaultSystemResources } from "./system-resources.js";
+import { recommendSystemResources } from "./resource-advisor.js";
+import { loadEcosystemUpdates as defaultEcosystemUpdates } from "./ecosystem-updates.js";
+import { getObservabilityProbe, registerObservabilityProbe } from "./probe-registry.js";
+
+export const SOFT_LINK_WINDOW_MS = 60 * 60 * 1000;
+const RUN_TS = ["updatedAt", "endedAt", "startedAt"];
+const REVIEW_TS = ["updatedAt", "createdAt", "capturedAt", "startedAt"];
+const GOV_PRIMARY = new Set([
+  CONTROL_PLANE_HEALTH.NOT_CONFIGURED,
+  CONTROL_PLANE_HEALTH.ACTION_REQUIRED,
+  CONTROL_PLANE_HEALTH.CHECK_FAILED
+]);
+
+function defaultEnsure() {
+  if (!getObservabilityProbe("gentle")) registerObservabilityProbe(createGentleProbe());
+  if (!getObservabilityProbe("graphify")) registerObservabilityProbe(createGraphifyProbe());
+  if (!getObservabilityProbe("hermes")) registerObservabilityProbe(createHermesProbe());
+}
+
+function emptyHermesActivity() {
+  return {
+    state: "error", error: "error", diagnostics: [], baseUrl: null, sessions: [],
+    aggregates: { returnedCount: 0, activeCount: 0, endedCount: 0, hasMore: false, lastActiveAt: null }
+  };
+}
+function summarizeHermesActivity(a) {
+  if (a == null || typeof a !== "object") return emptyHermesActivity();
+  const empty = emptyHermesActivity();
+  return {
+    state: a.state ?? "error", error: a.error ?? null, baseUrl: a.baseUrl ?? null,
+    diagnostics: Array.isArray(a.diagnostics) ? a.diagnostics.map(String) : [],
+    sessions: Array.isArray(a.sessions) ? a.sessions : [], aggregates: a.aggregates ?? empty.aggregates
+  };
+}
+
+function emptyEcosystemUpdates() {
+  return {
+    state: "error", checkedAt: null, cacheHit: false, diagnostics: [],
+    tools: {
+      kairo: { id: "kairo", state: "error", updateAvailable: false },
+      hermes: { id: "hermes", state: "error", updateAvailable: false },
+      gentle: { id: "gentle", state: "error", updateAvailable: false },
+      skills: { id: "skills", state: "error", updateAvailable: false }
+    }
+  };
+}
+function summarizeEcosystemUpdates(raw) {
+  if (raw == null || typeof raw !== "object") return emptyEcosystemUpdates();
+  return {
+    state: raw.state ?? "error",
+    checkedAt: raw.checkedAt ?? null,
+    cacheHit: raw.cacheHit === true,
+    diagnostics: Array.isArray(raw.diagnostics) ? raw.diagnostics.map(String) : [],
+    tools: raw.tools ?? emptyEcosystemUpdates().tools
+  };
+}
+
+function emptySystemResources() {
+  return {
+    state: "error", sampledAt: null, diagnostics: [],
+    memory: null, swap: null, disk: null,
+    processes: { totalCount: 0, zombieCount: 0, tracked: [] },
+    thermal: { state: "unavailable" }, ssdWear: { state: "unavailable" }
+  };
+}
+function summarizeSystemResources(raw) {
+  if (raw == null || typeof raw !== "object") return emptySystemResources();
+  const empty = emptySystemResources();
+  return {
+    state: raw.state ?? "error",
+    sampledAt: raw.sampledAt ?? null,
+    diagnostics: Array.isArray(raw.diagnostics) ? raw.diagnostics.map(String) : [],
+    memory: raw.memory ?? null, swap: raw.swap ?? null, disk: raw.disk ?? null,
+    processes: raw.processes ?? empty.processes,
+    thermal: raw.thermal ?? { state: "unavailable" },
+    ssdWear: raw.ssdWear ?? { state: "unavailable" }
+  };
+}
+
+export function parseCompanionTimestamp(value) {
+  if (value == null || value === "") return null;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  const ms = Date.parse(String(value));
+  return Number.isFinite(ms) ? ms : null;
+}
+
+function firstTs(obj, keys) {
+  for (const key of keys) {
+    const ms = parseCompanionTimestamp(obj?.[key]);
+    if (ms != null) return ms;
+  }
+  return null;
+}
+
+export const resolveRunTimestamp = (run) => firstTs(run, RUN_TS);
+export const resolveReviewTimestamp = (review) => firstTs(review, REVIEW_TS);
+
+/** Soft/display-only — never authority evidence. */
+export function softLinkReviewToRun(review, runs = []) {
+  const agentId = review?.agentId;
+  const reviewAt = resolveReviewTimestamp(review);
+  if (typeof agentId !== "string" || !agentId || reviewAt == null) return null;
+  const eligible = [];
+  for (const run of runs) {
+    if (run?.agentId !== agentId) continue;
+    const runAt = resolveRunTimestamp(run);
+    if (runAt == null || !(reviewAt > runAt)) continue;
+    const deltaMs = reviewAt - runAt;
+    if (deltaMs > SOFT_LINK_WINDOW_MS) continue;
+    const runId = String(run.runId ?? "");
+    if (!runId) continue;
+    eligible.push({ runId, runAt, deltaMs });
+  }
+  if (!eligible.length) return null;
+  eligible.sort((a, b) => (b.runAt - a.runAt) || a.runId.localeCompare(b.runId));
+  const best = eligible[0];
+  return {
+    kind: "soft", displayOnly: true, agentId,
+    reviewId: String(review.reviewId ?? ""), runId: best.runId,
+    deltaMs: best.deltaMs, runAt: best.runAt, reviewAt
+  };
+}
+
+export function summarizeCompanionProbes(probes = []) {
+  const byId = Object.fromEntries((probes ?? []).map((p) => [p.id, p]));
+  const gentle = byId.gentle ?? { state: "missing", diagnostics: [], error: null };
+  const graphify = byId.graphify ?? { state: "missing", diagnostics: [], error: null };
+  const graph = (graphify.evidence ?? []).find((e) => e?.kind === "graph") ?? null;
+  return {
+    gentle: { state: gentle.state, error: gentle.error ?? null, diagnostics: gentle.diagnostics ?? [] },
+    graphify: {
+      state: graphify.state, error: graphify.error ?? null,
+      diagnostics: graphify.diagnostics ?? [], graphStatus: graph?.status ?? null
+    }
+  };
+}
+
+function rankNext({ controlPlaneHealth, signals, engram }) {
+  const gentleState = signals?.gentle?.state;
+  const graphState = signals?.graphify?.state;
+  const graphStatus = signals?.graphify?.graphStatus;
+  const engramStatus = engram?.status ?? "missing";
+  let kind = "idle";
+  let title = "Companion signals quiet";
+  let detail = "No companion follow-up required.";
+  if (gentleState === "error" || graphState === "error" || graphStatus === "error"
+    || engramStatus === "error" || engramStatus === "conflict" || engramStatus === "unsupported") {
+    kind = "investigate";
+    title = "Investigate companion diagnostics";
+    detail = "Optional tools reported a hard failure; inspect Gentle/Graphify/Engram read-only.";
+  } else if (gentleState === "missing" || graphState === "missing" || engramStatus === "missing") {
+    kind = "missing";
+    title = "Optional companion tool not detected";
+    detail = "Governance may still be healthy; missing tools are diagnostic only.";
+  } else if (graphStatus === "stale") {
+    kind = "inform";
+    title = "Graphify graph looks stale";
+    detail = "Informational only — stale does not block read-only ops.";
+  }
+  return {
+    kind, title, detail, secondary: true,
+    governancePrimary: GOV_PRIMARY.has(controlPlaneHealth), displayOnly: true
+  };
+}
+
+function emptyCompanion(error = null) {
+  return {
+    ok: false, error: error == null ? null : String(error),
+    generatedAt: new Date().toISOString(),
+    signals: {
+      gentle: { state: "error", error: null, diagnostics: [] },
+      graphify: { state: "error", error: null, diagnostics: [], graphStatus: null },
+      hermes: { activity: emptyHermesActivity() },
+      system: { resources: emptySystemResources(), advice: { recommendations: [], deepScan: false } },
+      ecosystem: { updates: emptyEcosystemUpdates() }
+    },
+    engram: { status: "error", binary: null },
+    links: [], alertsCount: null,
+    nextSafeAction: {
+      kind: "investigate", title: "Investigate companion diagnostics",
+      detail: String(error ?? "companion snapshot failed"),
+      secondary: true, governancePrimary: false, displayOnly: true
+    }
+  };
+}
+
+/** Fail-soft companion snapshot for Cockpit overlay — never throws. */
+export async function buildCompanionSnapshot({
+  controlPlaneHealth = null, runs = [], reviews = null, alerts = null,
+  buildObservability = defaultObs, inspectEngram = null,
+  ensureRegistered = defaultEnsure, loadReviews = null, loadAlerts = null,
+  loadHermesActivity = defaultHermesActivity,
+  loadSystemResources = defaultSystemResources,
+  loadEcosystemUpdates = defaultEcosystemUpdates,
+  resourceDeepScan = false,
+  observabilityContext = {}
+} = {}) {
+  try {
+    ensureRegistered();
+    let obs;
+    try { obs = await buildObservability(observabilityContext); }
+    catch (err) { return emptyCompanion(err?.message ?? err); }
+
+    let engram = { status: "missing", binary: null };
+    if (typeof inspectEngram === "function") {
+      try { engram = inspectEngram(observabilityContext) ?? engram; }
+      catch (err) { engram = { status: "error", binary: null, error: err?.message ?? String(err) }; }
+    }
+
+    let hermesActivity = emptyHermesActivity();
+    try {
+      hermesActivity = summarizeHermesActivity(
+        await loadHermesActivity({ ...(observabilityContext ?? {}) })
+      );
+    } catch {
+      hermesActivity = emptyHermesActivity();
+    }
+
+    let systemResources = emptySystemResources();
+    try {
+      systemResources = summarizeSystemResources(
+        await loadSystemResources({ ...(observabilityContext ?? {}) })
+      );
+    } catch {
+      systemResources = emptySystemResources();
+    }
+    const systemAdvice = recommendSystemResources(systemResources, {
+      deepScan: resourceDeepScan === true
+    });
+
+    let ecosystemUpdates = emptyEcosystemUpdates();
+    try {
+      ecosystemUpdates = summarizeEcosystemUpdates(
+        await loadEcosystemUpdates({
+          ...(observabilityContext ?? {}),
+          packageName: observabilityContext?.packageName,
+          installedVersion: observabilityContext?.installedVersion ?? observabilityContext?.cliVersion,
+          homeDir: observabilityContext?.homeDir
+        })
+      );
+    } catch {
+      ecosystemUpdates = emptyEcosystemUpdates();
+    }
+
+    const reviewList = Array.isArray(reviews)
+      ? reviews
+      : (typeof loadReviews === "function" ? await loadReviews() : []);
+    const alertList = Array.isArray(alerts)
+      ? alerts
+      : (typeof loadAlerts === "function" ? await loadAlerts() : null);
+    const signals = {
+      ...summarizeCompanionProbes(obs?.probes ?? []),
+      hermes: { activity: hermesActivity },
+      system: { resources: systemResources, advice: systemAdvice },
+      ecosystem: { updates: ecosystemUpdates }
+    };
+    const links = [];
+    for (const review of reviewList ?? []) {
+      const link = softLinkReviewToRun(review, runs);
+      if (link) links.push(link);
+    }
+    return {
+      ok: true, error: null, generatedAt: new Date().toISOString(), signals,
+      engram: { status: engram.status ?? "missing", binary: engram.binary?.path ?? null, error: engram.error ?? null },
+      links,
+      alertsCount: Array.isArray(alertList)
+        ? alertList.filter((a) => a?.state === "open" || a?.state === "pending").length
+        : null,
+      nextSafeAction: rankNext({ controlPlaneHealth, signals, engram })
+    };
+  } catch (err) {
+    return emptyCompanion(err?.message ?? err);
+  }
+}

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

@@ -0,0 +1,24 @@
+import { normalizeProbeResult } from "./probe-contract.js";
+import { listObservabilityProbes } from "./probe-registry.js";
+
+/** Parallel soft snapshot — never throws for individual probe failures. */
+export async function buildObservabilitySnapshot(context = {}) {
+  const registered = listObservabilityProbes();
+  const settled = await Promise.allSettled(
+    registered.map(async (probe) => normalizeProbeResult(await probe.probe(context), probe.id))
+  );
+  const probes = settled.map((entry, i) => {
+    const id = registered[i].id;
+    if (entry.status === "fulfilled") return entry.value;
+    return normalizeProbeResult({
+      id,
+      state: "error",
+      error: entry.reason?.message ?? String(entry.reason ?? "probe failed")
+    }, id);
+  });
+  return {
+    generatedAt: new Date().toISOString(),
+    probes,
+    byId: Object.fromEntries(probes.map((p) => [p.id, p]))
+  };
+}