@kal-elsam/kairo-runtime 0.10.0 → 0.12.0

package/src/global/observability/ecosystem-updates.js

@@ -0,0 +1,224 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { fetchPublishedVersion } from "../npm-registry.js";
+import { harnessHomePaths } from "../paths.js";
+import { probeCommand as defaultProbeCommand } from "../cli-probe.js";
+
+export const ECOSYSTEM_UPDATES_CACHE_MS = 24 * 60 * 60 * 1000;
+export const ECOSYSTEM_UPDATES_TIMEOUT_MS = 8000;
+export const AGENT_SKILLS_PINNED_REV = "d2478bf0c73a6357df39a3ed6aff16acaa218843";
+export const AGENT_SKILLS_UPSTREAM =
+  "https://api.github.com/repos/addyosmani/agent-skills/commits/HEAD";
+
+const TOOL_IDS = Object.freeze(["kairo", "hermes", "gentle", "skills"]);
+
+function emptyTool(id, state = "unavailable") {
+  return {
+    id, state, installed: null, latest: null, updateAvailable: false,
+    provenance: null, error: state === "error" || state === "unavailable" ? state : null
+  };
+}
+
+function envelope(partial = {}) {
+  return {
+    state: "error", checkedAt: null, cacheHit: false, diagnostics: [],
+    tools: Object.fromEntries(TOOL_IDS.map((id) => [id, emptyTool(id)])),
+    ...partial
+  };
+}
+
+function whichAbsolute(command, env, probeCommand) {
+  const which = probeCommand("which", [command], { env, timeoutMs: 3000 });
+  if (!which?.ok) return "";
+  const path = String(which.stdout ?? "").trim().split(/\r?\n/)[0] ?? "";
+  return isAbsolute(path) ? path : "";
+}
+
+function compareSemver(a, b) {
+  const parse = (v) => String(v).replace(/^v/, "").split(".").map((p) => Number.parseInt(p, 10) || 0);
+  const aa = parse(a), bb = parse(b);
+  for (let i = 0; i < Math.max(aa.length, bb.length); i += 1) {
+    const d = (aa[i] ?? 0) - (bb[i] ?? 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+export function parseGentleUpdateOutput(stdout) {
+  const tools = [];
+  for (const line of String(stdout ?? "").split(/\r?\n/)) {
+    const m = line.match(/\[(ok|UP)\]\s+(\S+)\s+installed:\s+(\S+)\s+latest:\s+(\S+)/i);
+    if (m) tools.push({ name: m[2], installed: m[3], latest: m[4], updateAvailable: m[1].toUpperCase() === "UP" });
+  }
+  return tools;
+}
+
+export function parseHermesUpdateCheck(stdout, stderr, ok) {
+  const text = `${stdout ?? ""}\n${stderr ?? ""}`;
+  if (/update available|behind|new version|commits? behind/i.test(text)) {
+    return { state: "available", updateAvailable: true };
+  }
+  if (/up to date|already up.to.date|no update/i.test(text)) {
+    return { state: "available", updateAvailable: false };
+  }
+  if (!ok || /failed|fatal|error|unable/i.test(text)) {
+    return { state: "error", updateAvailable: false, error: "check_failed" };
+  }
+  return { state: "partial", updateAvailable: false };
+}
+
+async function checkKairo({ packageName, installedVersion, fetchVersion }) {
+  try {
+    const latest = await fetchVersion(packageName);
+    if (typeof latest !== "string" || !latest) {
+      return { ...emptyTool("kairo", "error"), installed: installedVersion, error: "malformed", provenance: "npm" };
+    }
+    return {
+      id: "kairo", state: "available", installed: installedVersion, latest,
+      updateAvailable: compareSemver(latest, installedVersion) > 0,
+      provenance: "npm-registry", error: null
+    };
+  } catch (err) {
+    const offline = /ENOTFOUND|ECONN|network|fetch|HTTP|timed?\s*out/i.test(String(err?.message ?? err));
+    return {
+      ...emptyTool("kairo", offline ? "unavailable" : "error"),
+      installed: installedVersion, provenance: "npm-registry",
+      error: offline ? "offline" : "check_failed"
+    };
+  }
+}
+
+function checkHermes({ env, probeCommand, timeoutMs }) {
+  const bin = whichAbsolute("hermes", env, probeCommand);
+  if (!bin) return emptyTool("hermes", "unavailable");
+  const res = probeCommand(bin, ["update", "--check"], { env, timeoutMs });
+  if (res?.timedOut) return { ...emptyTool("hermes", "error"), error: "timeout", provenance: bin };
+  const parsed = parseHermesUpdateCheck(res?.stdout, res?.stderr, Boolean(res?.ok));
+  return {
+    id: "hermes", state: parsed.state, installed: null, latest: null,
+    updateAvailable: parsed.updateAvailable === true, provenance: bin, error: parsed.error ?? null
+  };
+}
+
+function checkGentle({ env, probeCommand, timeoutMs }) {
+  const bin = whichAbsolute("gentle-ai", env, probeCommand);
+  if (!bin) return emptyTool("gentle", "unavailable");
+  const res = probeCommand(bin, ["update"], { env, timeoutMs });
+  if (res?.timedOut) return { ...emptyTool("gentle", "error"), error: "timeout", provenance: bin };
+  if (!res?.ok && !res?.stdout) return { ...emptyTool("gentle", "error"), error: "check_failed", provenance: bin };
+  const rows = parseGentleUpdateOutput(res.stdout);
+  if (rows.length === 0) return { ...emptyTool("gentle", "partial"), provenance: bin, error: "malformed" };
+  const root = rows.find((r) => r.name === "gentle-ai") ?? rows[0];
+  return {
+    id: "gentle", state: "available", installed: root.installed, latest: root.latest,
+    updateAvailable: rows.some((r) => r.updateAvailable), provenance: bin, error: null
+  };
+}
+
+async function checkSkills({ pinnedRev, fetchJson }) {
+  try {
+    const meta = await fetchJson(AGENT_SKILLS_UPSTREAM);
+    const sha = typeof meta?.sha === "string" ? meta.sha : null;
+    if (!sha || !/^[0-9a-f]{7,40}$/i.test(sha)) {
+      return { ...emptyTool("skills", "error"), installed: pinnedRev, error: "malformed", provenance: "github" };
+    }
+    const exactDiff = sha.toLowerCase() !== pinnedRev.toLowerCase()
+      && !(pinnedRev.length >= 7 && sha.toLowerCase().startsWith(pinnedRev.toLowerCase()));
+    return {
+      id: "skills", state: "available", installed: pinnedRev, latest: sha,
+      updateAvailable: exactDiff, provenance: "github-commits-api", error: null
+    };
+  } catch (err) {
+    const offline = /ENOTFOUND|ECONN|network|fetch|HTTP|403|429|timed?\s*out/i.test(String(err?.message ?? err));
+    return {
+      ...emptyTool("skills", offline ? "unavailable" : "error"),
+      installed: pinnedRev, provenance: "github-commits-api",
+      error: offline ? "offline" : "check_failed"
+    };
+  }
+}
+
+function aggregateState(tools) {
+  const states = TOOL_IDS.map((id) => tools[id]?.state);
+  if (states.every((s) => s === "unavailable")) return "unavailable";
+  if (states.some((s) => s === "error" || s === "partial" || s === "unavailable")) return "partial";
+  return "available";
+}
+
+/** Read-only ecosystem update detection. Never invokes mutating updaters. */
+export async function loadEcosystemUpdates({
+  packageName = "@kal-elsam/kairo-runtime",
+  installedVersion = "0.0.0",
+  homeDir,
+  env = process.env,
+  nowMs = Date.now(),
+  cacheTtlMs = ECOSYSTEM_UPDATES_CACHE_MS,
+  timeoutMs = ECOSYSTEM_UPDATES_TIMEOUT_MS,
+  forceRefresh = false,
+  pinnedSkillsRev = AGENT_SKILLS_PINNED_REV,
+  probeCommand = defaultProbeCommand,
+  fetchVersion = fetchPublishedVersion,
+  fetchJson = defaultFetchJson,
+  readCacheFile = async (p) => { try { return JSON.parse(await readFile(p, "utf8")); } catch { return null; } },
+  writeCacheFile = async (p, payload) => {
+    try {
+      await mkdir(join(p, ".."), { recursive: true });
+      await writeFile(p, `${JSON.stringify(payload)}\n`, "utf8");
+    } catch { /* best-effort */ }
+  }
+} = {}) {
+  const cachePath = homeDir
+    ? join(harnessHomePaths(homeDir).root, "cache", "ecosystem-updates.json")
+    : null;
+
+  if (!forceRefresh && cachePath) {
+    const cached = await readCacheFile(cachePath);
+    const checkedAt = cached?.checkedAt ? Date.parse(cached.checkedAt) : NaN;
+    if (Number.isFinite(checkedAt) && (nowMs - checkedAt) < cacheTtlMs && cached?.tools) {
+      return envelope({
+        state: cached.state ?? aggregateState(cached.tools),
+        checkedAt: cached.checkedAt, cacheHit: true,
+        diagnostics: Array.isArray(cached.diagnostics) ? cached.diagnostics : [],
+        tools: cached.tools
+      });
+    }
+  }
+
+  const perToolTimeout = Math.max(1000, Math.floor(timeoutMs / 2));
+  try {
+    const settled = await Promise.race([
+      Promise.all([
+        checkKairo({ packageName, installedVersion, fetchVersion }),
+        Promise.resolve().then(() => checkHermes({ env, probeCommand, timeoutMs: perToolTimeout })),
+        Promise.resolve().then(() => checkGentle({ env, probeCommand, timeoutMs: perToolTimeout })),
+        checkSkills({ pinnedRev: pinnedSkillsRev, fetchJson })
+      ]),
+      new Promise((_, reject) => setTimeout(() => reject(new Error("timeout")), timeoutMs))
+    ]);
+    const tools = { kairo: settled[0], hermes: settled[1], gentle: settled[2], skills: settled[3] };
+    const payload = envelope({
+      state: aggregateState(tools),
+      checkedAt: new Date(nowMs).toISOString(),
+      cacheHit: false, diagnostics: [], tools
+    });
+    if (cachePath) await writeCacheFile(cachePath, payload);
+    return payload;
+  } catch (err) {
+    const isTimeout = /timeout/i.test(String(err?.message ?? err));
+    return envelope({
+      state: isTimeout ? "error" : "unavailable",
+      checkedAt: new Date(nowMs).toISOString(),
+      cacheHit: false,
+      diagnostics: [isTimeout ? "ecosystem updates timeout" : "ecosystem updates error"],
+      tools: Object.fromEntries(TOOL_IDS.map((id) => [id, emptyTool(id, isTimeout ? "error" : "unavailable")]))
+    });
+  }
+}
+
+async function defaultFetchJson(url) {
+  const response = await fetch(url, {
+    headers: { Accept: "application/vnd.github+json", "User-Agent": "kairo-ecosystem-updates" }
+  });
+  if (!response.ok) throw new Error(`Failed to fetch ${url}: HTTP ${response.status}`);
+  return response.json();
+}

package/src/global/observability/gentle-bundle-export.js

@@ -0,0 +1,71 @@
+import { isAbsolute } from "node:path";
+import { probeCommand as defaultProbeCommand } from "../cli-probe.js";
+import { probeGentle as defaultProbeGentle } from "./gentle-probe.js";
+
+const EXPORT_TIMEOUT_MS = 60_000;
+
+/** Require negotiated absolute binary evidence — never fall back to PATH names. */
+export function resolveNegotiatedGentleBinary(probe) {
+  const path = (probe?.evidence ?? []).find((e) => e.kind === "binary")?.path ?? null;
+  return typeof path === "string" && path && isAbsolute(path) ? path : null;
+}
+
+function fail(code, diagnostics, extra = {}) {
+  return {
+    ok: false, exitCode: 2, code,
+    diagnostics: diagnostics.map(String),
+    providerStatus: null, timedOut: false, ...extra
+  };
+}
+
+/**
+ * Transport-only export: invoke Gentle review-bundle-export.
+ * Never reads/rewrites bundle bytes; never surfaces raw provider stderr.
+ */
+export async function exportGentleReviewBundle({
+  lineage, outPath, cwd = process.cwd(), env = process.env,
+  probeGentle = defaultProbeGentle, probeCommand = defaultProbeCommand
+} = {}) {
+  if (typeof lineage !== "string" || !lineage.trim()) {
+    return fail("invalid_request", ["Missing lineage id."], { lineage: lineage ?? null, outPath: outPath ?? null });
+  }
+  if (typeof outPath !== "string" || !outPath.trim()) {
+    return fail("invalid_request", ["Missing --out path."], { lineage, outPath: outPath ?? null });
+  }
+
+  const probe = await probeGentle({ cwd, env });
+  if (probe.state !== "available") {
+    const code = ["missing", "incompatible", "error"].includes(probe.state)
+      ? `gentle_${probe.state}` : "gentle_error";
+    return fail(code, probe.diagnostics?.length ? probe.diagnostics : [`Gentle probe state: ${probe.state}`], {
+      lineage, outPath
+    });
+  }
+
+  const binary = resolveNegotiatedGentleBinary(probe);
+  if (!binary) {
+    return fail("gentle_binary_unbound", [
+      "Negotiated Gentle binary evidence missing or not absolute; refusing PATH fallback."
+    ], { lineage, outPath });
+  }
+
+  const provider = probeCommand(binary, [
+    "review-bundle-export", "--cwd", cwd, "--lineage", lineage, "--out", outPath
+  ], { cwd, env, timeoutMs: EXPORT_TIMEOUT_MS });
+
+  if (!provider.ok) {
+    const diagnostics = ["provider_error"];
+    if (provider.timedOut) diagnostics.push("timed_out");
+    if (provider.status != null) diagnostics.push(`status=${provider.status}`);
+    return fail("provider_error", diagnostics, {
+      lineage, outPath,
+      providerStatus: provider.status ?? null,
+      timedOut: Boolean(provider.timedOut)
+    });
+  }
+
+  return {
+    ok: true, exitCode: 0, code: "exported", lineage, outPath,
+    diagnostics: [], providerStatus: provider.status, timedOut: false, binary
+  };
+}

package/src/global/observability/gentle-bundle-import.js

@@ -0,0 +1,122 @@
+import { probeCommand as defaultProbeCommand } from "../cli-probe.js";
+import {
+  CONSENT_TYPES,
+  PermissionAuthorityError,
+  UNSAFE_OPERATIONS,
+  authorizeUnsafeOperation as defaultAuthorizeUnsafeOperation
+} from "../runtime/run-permissions.js";
+import { probeGentle as defaultProbeGentle } from "./gentle-probe.js";
+import { resolveNegotiatedGentleBinary } from "./gentle-bundle-export.js";
+
+const IMPORT_TIMEOUT_MS = 60_000;
+
+function fail(code, diagnostics, extra = {}) {
+  return {
+    ok: false,
+    exitCode: 2,
+    code,
+    mutationOutcome: "not_started",
+    diagnostics: diagnostics.map(String),
+    providerStatus: null,
+    timedOut: false,
+    permissionAuthority: null,
+    ...extra
+  };
+}
+
+/**
+ * Consent-gated transport: invoke Gentle review-bundle-import.
+ * Provider decides bundle format. Never parses bytes or surfaces raw stderr.
+ */
+export async function importGentleReviewBundle({
+  bundlePath,
+  cwd = process.cwd(),
+  env = process.env,
+  confirmImport = false,
+  probeGentle = defaultProbeGentle,
+  probeCommand = defaultProbeCommand,
+  authorizeUnsafeOperation = defaultAuthorizeUnsafeOperation
+} = {}) {
+  if (typeof bundlePath !== "string" || !bundlePath.trim()) {
+    return fail("invalid_request", ["Missing --bundle path."], {
+      bundlePath: bundlePath ?? null
+    });
+  }
+
+  let permissionAuthority = null;
+  try {
+    ({ permissionAuthority } = authorizeUnsafeOperation({
+      operation: UNSAFE_OPERATIONS.GENTLE_BUNDLE_IMPORT,
+      confirmed: Boolean(confirmImport),
+      source: "cli",
+      consentType: CONSENT_TYPES.CLI_CONFIRM_IMPORT
+    }));
+  } catch (error) {
+    if (error instanceof PermissionAuthorityError) {
+      return fail(error.code ?? "import_consent_required", [error.message], {
+        bundlePath, cwd
+      });
+    }
+    throw error;
+  }
+
+  const probe = await probeGentle({ cwd, env });
+  if (probe.state !== "available") {
+    const code = ["missing", "incompatible", "error"].includes(probe.state)
+      ? `gentle_${probe.state}` : "gentle_error";
+    return fail(
+      code,
+      probe.diagnostics?.length ? probe.diagnostics : [`Gentle probe state: ${probe.state}`],
+      { bundlePath, cwd, permissionAuthority }
+    );
+  }
+
+  const binary = resolveNegotiatedGentleBinary(probe);
+  if (!binary) {
+    return fail("gentle_binary_unbound", [
+      "Negotiated Gentle binary evidence missing or not absolute; refusing PATH fallback."
+    ], { bundlePath, cwd, permissionAuthority });
+  }
+
+  let provider;
+  try {
+    provider = probeCommand(binary, [
+      "review-bundle-import", "--cwd", cwd, "--bundle", bundlePath
+    ], { cwd, env, timeoutMs: IMPORT_TIMEOUT_MS });
+  } catch {
+    return fail("mutation_outcome_unknown", ["provider_error", "spawn_interrupted"], {
+      mutationOutcome: "unknown",
+      bundlePath, cwd, binary, permissionAuthority
+    });
+  }
+
+  const timedOut = Boolean(provider?.timedOut);
+  const status = provider?.status ?? null;
+  const committed = provider?.ok === true && status === 0 && timedOut !== true;
+  if (!committed) {
+    const diagnostics = ["provider_error"];
+    if (timedOut) diagnostics.push("timed_out");
+    if (status != null) diagnostics.push(`status=${status}`);
+    else diagnostics.push("status_unknown");
+    return fail("mutation_outcome_unknown", diagnostics, {
+      mutationOutcome: "unknown",
+      bundlePath, cwd, binary, permissionAuthority,
+      providerStatus: status,
+      timedOut
+    });
+  }
+
+  return {
+    ok: true,
+    exitCode: 0,
+    code: "imported",
+    mutationOutcome: "committed",
+    bundlePath,
+    cwd,
+    binary,
+    diagnostics: [],
+    providerStatus: status,
+    timedOut: false,
+    permissionAuthority
+  };
+}

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

@@ -0,0 +1,155 @@
+import { isAbsolute } from "node:path";
+import {
+  isExecutableAvailable,
+  parseVersionFromOutput,
+  probeCommand as defaultProbeCommand
+} from "../cli-probe.js";
+import { normalizeProbeResult } from "./probe-contract.js";
+
+export const SUPPORTED_PROTOCOL = Object.freeze({ major: 2, minor: 0 });
+export const SUPPORTED_SCHEMA = "gentle-ai.review-integration.capabilities/v2";
+export const SUPPORTED_CONTRACT = "gentle-ai.review-integration/v2";
+export const SUPPORTED_MANDATORY_FEATURES = Object.freeze([
+  "compact_v2_authority", "exact_receipt_replay", "five_delivery_gates",
+  "immutable_snapshot", "legacy_v1_target_scoped_read_only",
+  "repository_independent_capabilities", "restart_safe_projection",
+  "sdd_receipt_binding", "target_scoped_status", "uniform_failure_envelope"
+]);
+
+const SUPPORT_SET = new Set(SUPPORTED_MANDATORY_FEATURES);
+
+function result(partial) {
+  return normalizeProbeResult({
+    id: "gentle", version: null, contractCompatible: null,
+    diagnostics: [], evidence: [], error: null, ...partial
+  }, "gentle");
+}
+
+function defaultWhichAbsolute(command, env) {
+  if (!isExecutableAvailable(command, { env })) return "";
+  const which = defaultProbeCommand("which", [command], { env, timeoutMs: 3000 });
+  const path = String(which.stdout ?? "").trim().split(/\r?\n/)[0] ?? "";
+  return isAbsolute(path) ? path : "";
+}
+
+/** Resolve absolute Gentle binary; never return a bare command name. */
+export function resolveGentleBinaryPath(command = "gentle-ai", env = process.env, {
+  whichCommand = defaultWhichAbsolute
+} = {}) {
+  const resolved = whichCommand(command, env) || null;
+  return resolved && isAbsolute(resolved) ? resolved : null;
+}
+
+/** Package version is evidence only — never the compatibility gate. */
+export function evaluateGentleCapabilities(payload) {
+  const diagnostics = [];
+  const evidence = [{ kind: "capabilities", schema: payload?.schema ?? null }];
+  const version = payload?.package?.version ?? null;
+  if (payload == null || typeof payload !== "object" || Array.isArray(payload)) {
+    return result({
+      state: "error", version, evidence, error: "invalid capabilities payload",
+      diagnostics: ["Capabilities payload is not an object."]
+    });
+  }
+  if (payload.schema !== SUPPORTED_SCHEMA) {
+    diagnostics.push(`schema mismatch: got ${String(payload.schema)}`);
+  }
+  if (payload.contract !== SUPPORTED_CONTRACT) {
+    diagnostics.push(`contract mismatch: got ${String(payload.contract)}`);
+  }
+  if (payload.protocol?.major !== SUPPORTED_PROTOCOL.major) {
+    diagnostics.push(`protocol.major mismatch: got ${String(payload.protocol?.major)}`);
+  }
+  if (payload.protocol?.minor !== SUPPORTED_PROTOCOL.minor) {
+    diagnostics.push(`protocol.minor mismatch: got ${String(payload.protocol?.minor)}`);
+  }
+  const mandatory = payload.features?.mandatory;
+  if (!Array.isArray(mandatory)) {
+    diagnostics.push("features.mandatory must be an array.");
+  } else {
+    const seen = new Set();
+    for (const feature of mandatory) {
+      const name = feature?.name;
+      seen.add(name);
+      if (typeof name !== "string" || !SUPPORT_SET.has(name)) {
+        diagnostics.push(`unknown mandatory feature: ${String(name)}`);
+      } else if (feature.supported !== true) {
+        diagnostics.push(`mandatory feature not supported: ${name}`);
+      }
+    }
+    for (const required of SUPPORTED_MANDATORY_FEATURES) {
+      if (!seen.has(required)) diagnostics.push(`missing mandatory feature: ${required}`);
+    }
+  }
+  if (diagnostics.length) {
+    return result({ state: "incompatible", version, contractCompatible: false, diagnostics, evidence });
+  }
+  return result({ state: "available", version, contractCompatible: true, evidence });
+}
+
+export async function probeGentle({
+  env = process.env,
+  cwd = process.cwd(),
+  whichCommand = defaultWhichAbsolute,
+  probeCommand = defaultProbeCommand
+} = {}) {
+  const path = resolveGentleBinaryPath("gentle-ai", env, { whichCommand });
+  if (!path) {
+    return result({
+      state: "missing",
+      diagnostics: [
+        "gentle-ai absolute binary not resolved. Install Gentle AI separately, then re-run the probe."
+      ],
+      evidence: [{ kind: "binary", path: null }]
+    });
+  }
+  const evidence = [{ kind: "binary", path }];
+  const versionResult = probeCommand(path, ["--version"], { cwd, env, timeoutMs: 5000 });
+  const version = parseVersionFromOutput(`${versionResult.stdout}\n${versionResult.stderr}`);
+  evidence.push({ kind: "version", version, ok: versionResult.ok });
+
+  const capsResult = probeCommand(
+    path,
+    ["review", "capabilities", "--contract", SUPPORTED_CONTRACT],
+    { cwd, env, timeoutMs: 8000 }
+  );
+  evidence.push({ kind: "capabilities", ok: capsResult.ok, status: capsResult.status });
+  // Failed exit / timeout never promotes stdout into a negotiated capability.
+  if (capsResult.timedOut || capsResult.status !== 0) {
+    return result({
+      state: "error", version, evidence,
+      diagnostics: [
+        capsResult.timedOut
+          ? "gentle-ai review capabilities timed out"
+          : "gentle-ai review capabilities failed"
+      ],
+      error: capsResult.error ?? (capsResult.timedOut ? "timeout" : `exit ${capsResult.status}`)
+    });
+  }
+  let payload;
+  try {
+    payload = JSON.parse(String(capsResult.stdout ?? "").trim());
+  } catch (err) {
+    return result({
+      state: "error", version, evidence, error: err?.message ?? String(err),
+      diagnostics: ["Failed to parse capabilities JSON."]
+    });
+  }
+  const evaluated = evaluateGentleCapabilities(payload);
+  return result({
+    ...evaluated,
+    version: evaluated.version ?? version,
+    evidence: [...evidence, ...(evaluated.evidence ?? [])]
+  });
+}
+
+export function createGentleProbe(deps = {}) {
+  return {
+    id: "gentle",
+    declaredEvents: Object.freeze([]),
+    declaredActions: Object.freeze([]),
+    async probe(context = {}) {
+      return probeGentle({ ...deps, ...context, env: context.env ?? deps.env ?? process.env });
+    }
+  };
+}