@kal-elsam/kairo-runtime 0.11.0 → 0.13.0

package/src/global/observability/graphify-ops.js

@@ -0,0 +1,133 @@
+import { printJson } from "../json-output.js";
+import { commandHeader } from "../brand/index.js";
+import { probeCommand as defaultProbeCommand } from "../cli-probe.js";
+import {
+  assertGraphInsideWorkspace, inspectGraphArtifact, resolveGitHeadSha, resolveGraphifyBinaryPath
+} from "./graphify-probe.js";
+
+const OPS_TIMEOUT_MS = 15_000;
+const MAX_STDOUT_BYTES = 256_000;
+const DEFAULT_QUERY_BUDGET = 2000;
+const MAX_QUERY_BUDGET = 8000;
+const OPS = new Set(["query", "path", "explain"]);
+
+function fail(code, diagnostics, extra = {}) {
+  return {
+    ok: false, exitCode: 2, code, text: null, truncated: false, timedOut: false,
+    providerStatus: null, diagnostics: diagnostics.map(String),
+    op: null, graphPath: null, graphStatus: null, binary: null, ...extra
+  };
+}
+function clampBudget(raw) {
+  if (raw == null || raw === "") return DEFAULT_QUERY_BUDGET;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 1 && n <= MAX_QUERY_BUDGET ? n : null;
+}
+export async function runGraphifyOp({
+  op, args = [], graphPath, cwd = process.cwd(), workspaceRoot = cwd,
+  env = process.env, budget = DEFAULT_QUERY_BUDGET, whichCommand,
+  probeCommand = defaultProbeCommand, inspectGraph = inspectGraphArtifact,
+  containPath = assertGraphInsideWorkspace, headSha = null,
+  resolveHead = resolveGitHeadSha,
+  timeoutMs = OPS_TIMEOUT_MS, maxStdoutBytes = MAX_STDOUT_BYTES
+} = {}) {
+  if (!OPS.has(op)) return fail("invalid_request", [`Unknown graphify op "${op}".`], { op, graphPath });
+  if (typeof graphPath !== "string" || !graphPath.trim()) {
+    return fail("invalid_request", ["Missing --graph path."], { op, graphPath: graphPath ?? null });
+  }
+  let queryBudget = DEFAULT_QUERY_BUDGET;
+  if (op === "query") {
+    queryBudget = clampBudget(budget);
+    if (queryBudget == null) {
+      return fail("invalid_request", [`Invalid --budget (integer 1..${MAX_QUERY_BUDGET}).`], { op, graphPath });
+    }
+  }
+  const binary = resolveGraphifyBinaryPath("graphify", env, whichCommand ? { whichCommand } : {});
+  if (!binary) return fail("graphify_missing", ["graphify absolute binary not resolved."], { op, graphPath });
+
+  const contained = containPath(workspaceRoot, graphPath, { cwd });
+  if (!contained.ok) {
+    return fail(contained.code ?? "graph_path_outside_workspace", [
+      contained.code === "graph_path_outside_workspace"
+        ? "Resolved --graph is outside the workspace; refusing spawn."
+        : (contained.error ?? "Failed to resolve --graph path.")
+    ], { op, graphPath: contained.path, binary });
+  }
+
+  const head = (typeof headSha === "string" && headSha.trim())
+    ? headSha.trim()
+    : resolveHead(cwd);
+  const artifact = inspectGraph(contained.path, { cwd, headSha: head });
+  if (artifact.status === "missing" || artifact.status === "malformed" || artifact.status === "error") {
+    const code = artifact.status === "error" ? "graphify_error" : "graph_unavailable";
+    return fail(code, artifact.diagnostics?.length ? artifact.diagnostics : [`graph ${artifact.status}`], {
+      op, graphPath: artifact.path, graphStatus: artifact.status, binary
+    });
+  }
+
+  const argv = op === "query"
+    ? ["query", ...args.map(String), "--budget", String(queryBudget), "--graph", artifact.path]
+    : [op, ...args.map(String), "--graph", artifact.path];
+  let provider;
+  try { provider = probeCommand(binary, argv, { cwd, env, timeoutMs }); }
+  catch {
+    return fail("provider_error", ["provider_error", "spawn_interrupted"], {
+      op, graphPath: artifact.path, graphStatus: artifact.status, binary
+    });
+  }
+
+  const timedOut = Boolean(provider?.timedOut);
+  const status = provider?.status ?? null;
+  const raw = String(provider?.stdout ?? "");
+  const truncated = Buffer.byteLength(raw, "utf8") > maxStdoutBytes;
+  const text = truncated ? Buffer.from(raw, "utf8").subarray(0, maxStdoutBytes).toString("utf8") : raw;
+  const diagnostics = [...(artifact.diagnostics ?? [])];
+  if (truncated) diagnostics.push("stdout_truncated");
+  const ok = provider?.ok === true && status === 0 && timedOut !== true;
+  if (!ok) {
+    const d = ["provider_error", ...diagnostics, ...(timedOut ? ["timed_out"] : []), status != null ? `status=${status}` : "status_unknown"];
+    return fail(timedOut ? "timed_out" : "provider_error", d, {
+      op, graphPath: artifact.path, graphStatus: artifact.status, binary,
+      text: text || null, truncated, providerStatus: status, timedOut
+    });
+  }
+  return {
+    ok: true, exitCode: 0, code: "ok", op, graphPath: artifact.path, graphStatus: artifact.status,
+    text, truncated, diagnostics, providerStatus: status, timedOut: false, binary
+  };
+}
+
+export async function runGraphifyCli(options, _pkg, deps = {}) {
+  try {
+    if (!options.graphifyAction || !options.graphPath) {
+      throw new Error("Missing graphify action or --graph. Use: kairo graphify <query|path|explain> ... --graph <path>");
+    }
+    const result = await (deps.runGraphifyOp ?? runGraphifyOp)({
+      op: options.graphifyAction, args: options.graphifyArgs ?? [],
+      graphPath: options.graphPath, cwd: options.cwd ?? process.cwd(),
+      workspaceRoot: options.cwd ?? process.cwd(), budget: options.graphifyBudget,
+      headSha: options.headSha ?? deps.headSha ?? null,
+      resolveHead: deps.resolveHead
+    });
+    process.exitCode = result.exitCode;
+    if (options.json) {
+      printJson({
+        ok: result.ok, exitCode: result.exitCode, code: result.code, op: result.op,
+        graphPath: result.graphPath, graphStatus: result.graphStatus, text: result.text,
+        truncated: result.truncated, diagnostics: result.diagnostics,
+        providerStatus: result.providerStatus, timedOut: result.timedOut
+      });
+    } else if (result.ok) console.log(`${commandHeader(`graphify ${options.graphifyAction}`)}\n${result.text ?? ""}`);
+    else {
+      console.error(`graphify ${options.graphifyAction} failed (${result.code}).`);
+      for (const line of result.diagnostics ?? []) console.error(`  ${line}`);
+    }
+    return result;
+  } catch (error) {
+    const message = String(error?.message ?? error);
+    if (options.json) printJson({ ok: false, exitCode: 2, error: message, code: error?.code ?? null });
+    else console.error(message);
+    process.exitCode = 2;
+    return { exitCode: 2, error };
+  }
+}

package/src/global/observability/graphify-parse-cache.js

@@ -0,0 +1,90 @@
+import { statSync, realpathSync } from "node:fs";
+import { resolve } from "node:path";
+
+export const GRAPHIFY_PARSE_TTL_MS = 5_000;
+export const GRAPHIFY_PARSE_MAX_ENTRIES = 8;
+
+const CACHEABLE = new Set(["ok", "stale"]);
+
+/** @type {Map<string, { value: object, expiresAt: number }>} */
+const entries = new Map();
+
+export function resetGraphifyParseCacheForTests() {
+  entries.clear();
+}
+
+export function graphifyParseCacheSizeForTests() {
+  return entries.size;
+}
+
+function touch(key, entry) {
+  entries.delete(key);
+  entries.set(key, entry);
+}
+
+function evictOldest(maxEntries) {
+  while (entries.size > maxEntries) {
+    const oldest = entries.keys().next().value;
+    if (oldest == null) break;
+    entries.delete(oldest);
+  }
+}
+
+export function buildGraphifyParseIdentity(resolvedPath, headSha, {
+  stat = (p) => statSync(p)
+} = {}) {
+  const st = stat(resolvedPath);
+  return [
+    String(resolvedPath),
+    String(st.dev),
+    String(st.ino),
+    String(st.size),
+    String(st.mtimeMs),
+    String(headSha ?? "")
+  ].join("\0");
+}
+
+/**
+ * Passive ok|stale parse cache. missing|malformed|error never cached.
+ * Caller must pass `inspect` (usually inspectGraphArtifact) to avoid cycles.
+ * Graphify ops must keep calling inspectGraphArtifact directly.
+ */
+export function inspectGraphArtifactCached(graphPath, options = {}) {
+  const {
+    inspect,
+    now = Date.now,
+    ttlMs = GRAPHIFY_PARSE_TTL_MS,
+    maxEntries = GRAPHIFY_PARSE_MAX_ENTRIES,
+    stat = (p) => statSync(p),
+    realpath = (p) => realpathSync(p),
+    cwd = process.cwd(),
+    headSha = null,
+    ...rest
+  } = options;
+
+  if (typeof inspect !== "function") {
+    throw new Error("inspectGraphArtifactCached requires options.inspect");
+  }
+
+  if (typeof graphPath === "string" && graphPath.trim()) {
+    try {
+      const resolved = realpath(resolve(cwd, graphPath));
+      const identity = buildGraphifyParseIdentity(resolved, headSha, { stat });
+      const hit = entries.get(identity);
+      if (hit && hit.expiresAt > now()) {
+        touch(identity, hit);
+        return hit.value;
+      }
+      const result = inspect(graphPath, { ...rest, cwd, headSha, realpath });
+      if (CACHEABLE.has(result?.status)) {
+        touch(identity, { value: result, expiresAt: now() + ttlMs });
+        evictOldest(maxEntries);
+      }
+      return result;
+    } catch {
+      /* identity unavailable — fall through */
+    }
+  }
+
+  return inspect(graphPath, { ...rest, cwd, headSha, realpath });
+}

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

@@ -0,0 +1,185 @@
+import { spawnSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { isExecutableAvailable, probeCommand as defaultProbeCommand } from "../cli-probe.js";
+import { normalizeProbeResult } from "./probe-contract.js";
+import { inspectGraphArtifactCached } from "./graphify-parse-cache.js";
+
+export const GRAPH_REPORT_COMMIT_PATTERN = /Built from commit:\s*`([0-9a-f]+)`/i;
+
+/** Env keys that redirect Git away from cwd — strip before rev-parse. */
+const GIT_OVERRIDE_KEYS = Object.freeze([
+  "GIT_DIR", "GIT_WORK_TREE", "GIT_COMMON_DIR", "GIT_OBJECT_DIRECTORY",
+  "GIT_INDEX_FILE", "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CEILING_DIRECTORIES",
+  "GIT_NAMESPACE"
+]);
+
+export function scrubGitOverrideEnv(env = process.env) {
+  const clean = { ...env };
+  for (const key of GIT_OVERRIDE_KEYS) delete clean[key];
+  return clean;
+}
+
+/** Fail-soft productive HEAD bound to workspace top-level; never throws. */
+export function resolveGitHeadSha(cwd = process.cwd(), {
+  spawn = spawnSync, timeoutMs = 3000, env = process.env, realpath = realpathSync
+} = {}) {
+  try {
+    const cleanEnv = scrubGitOverrideEnv(env);
+    const opts = { cwd, encoding: "utf8", timeout: timeoutMs, env: cleanEnv };
+    const top = spawn("git", ["rev-parse", "--show-toplevel"], opts);
+    if (top.status !== 0) return null;
+    const topLevel = String(top.stdout ?? "").trim();
+    if (!topLevel) return null;
+    let wanted;
+    let actual;
+    try {
+      wanted = realpath(resolve(cwd));
+      actual = realpath(topLevel);
+    } catch {
+      return null;
+    }
+    if (wanted !== actual) return null;
+    const head = spawn("git", ["rev-parse", "HEAD"], opts);
+    if (head.status !== 0) return null;
+    const sha = String(head.stdout ?? "").trim();
+    return /^[0-9a-f]{7,64}$/i.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+function effectiveHeadSha(headSha, cwd, resolveHead) {
+  if (typeof headSha === "string" && headSha.trim()) return headSha.trim();
+  return resolveHead(cwd);
+}
+
+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 : "";
+}
+
+export function resolveGraphifyBinaryPath(command = "graphify", env = process.env, {
+  whichCommand = defaultWhichAbsolute
+} = {}) {
+  const resolved = whichCommand(command, env) || null;
+  return resolved && isAbsolute(resolved) ? resolved : null;
+}
+
+function ioFail(code, status, path, err) {
+  return { status, path, error: status === "missing" ? null : (err?.message ?? String(err)), diagnostics: [code] };
+}
+
+/** ENOENT→missing; invalid JSON / non-object / nodes|links not arrays→malformed; else error. */
+export function inspectGraphArtifact(graphPath, {
+  cwd = process.cwd(), readFile = (p) => readFileSync(p, "utf8"),
+  realpath = (p) => realpathSync(p), headSha = null
+} = {}) {
+  if (typeof graphPath !== "string" || !graphPath.trim()) {
+    return { status: "error", path: null, error: "missing graph path", diagnostics: ["invalid_request"] };
+  }
+  const abs = resolve(cwd, graphPath);
+  let resolved;
+  try { resolved = realpath(abs); }
+  catch (err) {
+    const missing = err?.code === "ENOENT";
+    return ioFail(missing ? "graph_missing" : "realpath_error", missing ? "missing" : "error", abs, err);
+  }
+  let raw;
+  try { raw = readFile(resolved); }
+  catch (err) {
+    const missing = err?.code === "ENOENT";
+    return ioFail(missing ? "graph_missing" : "read_error", missing ? "missing" : "error", resolved, err);
+  }
+  let payload;
+  try { payload = JSON.parse(String(raw)); }
+  catch { return { status: "malformed", path: resolved, error: null, diagnostics: ["invalid_json"] }; }
+  if (payload == null || typeof payload !== "object" || Array.isArray(payload)
+    || !Array.isArray(payload.nodes) || !Array.isArray(payload.links)) {
+    return { status: "malformed", path: resolved, error: null, diagnostics: ["nodes_or_links_invalid"] };
+  }
+  const diagnostics = [];
+  let status = "ok";
+  if (typeof headSha === "string" && headSha) {
+    try {
+      const m = String(readFile(join(dirname(resolved), "GRAPH_REPORT.md"))).match(GRAPH_REPORT_COMMIT_PATTERN);
+      if (m && !(headSha.startsWith(m[1]) || m[1].startsWith(headSha))) {
+        status = "stale";
+        diagnostics.push(`stale graph=${m[1]} head=${headSha.slice(0, 8)}`);
+      }
+    } catch { /* missing report → ok */ }
+  }
+  return { status, path: resolved, error: null, diagnostics };
+}
+
+/** realpath(--graph) inside workspace; missing leaf OK if parent is inside. */
+export function assertGraphInsideWorkspace(workspaceRoot, graphPath, {
+  cwd = process.cwd(), realpath = (p) => realpathSync(p)
+} = {}) {
+  let root;
+  try { root = realpath(resolve(cwd, workspaceRoot)); }
+  catch (err) {
+    return { ok: false, code: "graphify_error", path: resolve(cwd, graphPath), root: null, error: err?.message };
+  }
+  const abs = resolve(cwd, graphPath);
+  let target;
+  try { target = realpath(abs); }
+  catch (err) {
+    if (err?.code !== "ENOENT") return { ok: false, code: "graphify_error", path: abs, root, error: err?.message };
+    try { target = join(realpath(dirname(abs)), basename(abs)); }
+    catch (e) {
+      return { ok: false, code: e?.code === "ENOENT" ? "graph_unavailable" : "graphify_error", path: abs, root, error: e?.message };
+    }
+  }
+  const rel = relative(root, target);
+  if (rel.startsWith("..") || isAbsolute(rel)) {
+    return { ok: false, code: "graph_path_outside_workspace", path: target, root };
+  }
+  return { ok: true, code: null, path: target, root };
+}
+
+export async function probeGraphify({
+  env = process.env, cwd = process.cwd(), whichCommand = defaultWhichAbsolute,
+  inspectGraph = (path, opts) => inspectGraphArtifactCached(path, {
+    ...opts, inspect: inspectGraphArtifact
+  }),
+  headSha = null, resolveHead = resolveGitHeadSha
+} = {}) {
+  let path = null;
+  try {
+    path = resolveGraphifyBinaryPath("graphify", env, { whichCommand });
+    if (!path) {
+      return normalizeProbeResult({
+        id: "graphify", state: "missing", diagnostics: ["graphify absolute binary not resolved."],
+        evidence: [{ kind: "binary", path: null }]
+      }, "graphify");
+    }
+    const head = effectiveHeadSha(headSha, cwd, resolveHead);
+    const graph = inspectGraph(join(cwd, "graphify-out", "graph.json"), { cwd, headSha: head });
+    const state = graph.status === "error" ? "error" : "available";
+    return normalizeProbeResult({
+      id: "graphify", state, diagnostics: [...(graph.diagnostics ?? [])],
+      evidence: [{ kind: "binary", path }, { kind: "graph", path: graph.path, status: graph.status }],
+      error: graph.status === "error" ? graph.error : null
+    }, "graphify");
+  } catch (err) {
+    return normalizeProbeResult({
+      id: "graphify", state: "error", evidence: [{ kind: "binary", path }],
+      diagnostics: [path ? "graph inspect failed" : "graphify binary resolve failed"],
+      error: err?.message ?? String(err)
+    }, "graphify");
+  }
+}
+
+export function createGraphifyProbe(deps = {}) {
+  return {
+    id: "graphify",
+    declaredEvents: Object.freeze([]),
+    declaredActions: Object.freeze(["query", "path", "explain"]),
+    async probe(context = {}) {
+      return probeGraphify({ ...deps, ...context, env: context.env ?? deps.env ?? process.env });
+    }
+  };
+}

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

@@ -0,0 +1,163 @@
+import { fetchJson } from "../intelligence/http.js";
+
+export const DEFAULT_HERMES_API_URL = "http://127.0.0.1:8642";
+export const HERMES_ACTIVITY_LIMIT_DEFAULT = 20;
+export const HERMES_ACTIVITY_LIMIT_MAX = 50;
+export const HERMES_ACTIVITY_TIMEOUT_MS = 2000;
+export const HERMES_ACTIVE_WINDOW_MS = 5 * 60 * 1000;
+const LOOPBACK = new Set(["127.0.0.1", "localhost", "::1"]);
+
+function emptyAgg() {
+  return { returnedCount: 0, activeCount: 0, endedCount: 0, hasMore: false, lastActiveAt: null };
+}
+function out(partial) {
+  return { state: "error", error: null, diagnostics: [], baseUrl: null, sessions: [], aggregates: emptyAgg(), ...partial };
+}
+function opaque(state, diagnostics, baseUrl = null) {
+  return out({ state, error: state, diagnostics: diagnostics.map(String), baseUrl });
+}
+
+/** Loopback HTTP(S) only — no embedded credentials. */
+export function assertHermesLoopbackUrl(raw) {
+  try {
+    const url = new URL(String(raw ?? ""));
+    if (url.protocol !== "http:" && url.protocol !== "https:") return { ok: false, reason: "protocol" };
+    if (url.username || url.password) return { ok: false, reason: "credentials" };
+    if (!LOOPBACK.has(url.hostname.replace(/^\[|\]$/g, ""))) return { ok: false, reason: "not_loopback" };
+    return { ok: true, url: url.origin };
+  } catch { return { ok: false, reason: "invalid_url" }; }
+}
+
+function clampLimit(limit) {
+  const n = Number(limit);
+  return Number.isFinite(n)
+    ? Math.min(HERMES_ACTIVITY_LIMIT_MAX, Math.max(1, Math.trunc(n)))
+    : HERMES_ACTIVITY_LIMIT_DEFAULT;
+}
+
+async function hermesGet(url, { apiKey, timeoutMs, fetchImpl }) {
+  const headers = { Accept: "application/json" };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  const wrapped = (input, init = {}) => fetchImpl(input, { ...init, method: "GET", redirect: "error" });
+  return fetchJson(url, { method: "GET", headers, timeoutMs, fetchImpl: wrapped });
+}
+
+function classifyTransport(res) {
+  if (res?.status === 401 || res?.status === 403) return "auth_required";
+  if (res?.status >= 500 || res?.error === "request timed out") return "error";
+  if (res?.status === 0) return /timed?\s*out|abort/.test(String(res.error ?? "")) ? "error" : "unavailable";
+  return null;
+}
+
+function isJson(data) {
+  return data != null && typeof data === "object" && !Array.isArray(data) && !("raw" in data);
+}
+
+/** Upstream: features.session_resources + endpoints.sessions {method,path}. */
+export function capabilitiesAdvertiseSessionsList(caps) {
+  if (caps?.features?.session_resources !== true) return false;
+  const ep = caps?.endpoints?.sessions;
+  if (ep == null || typeof ep !== "object" || Array.isArray(ep)) return false;
+  return String(ep.method).toUpperCase() === "GET" && ep.path === "/api/sessions";
+}
+
+function parseTs(value) {
+  if (value == null) return { ok: true, ms: null };
+  if (typeof value !== "number" || !Number.isFinite(value)) return { ok: false };
+  const ms = value > 1e12 ? value : value * 1000;
+  if (!Number.isFinite(ms) || Math.abs(ms) > 8.64e15) return { ok: false };
+  return { ok: true, ms };
+}
+function countOrZero(value) {
+  if (value == null) return { ok: true, n: 0 };
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) return { ok: false };
+  return { ok: true, n: value };
+}
+function optString(value) {
+  if (value == null) return { ok: true, s: null };
+  return typeof value === "string" ? { ok: true, s: value } : { ok: false };
+}
+
+/** Official session row. Null on bad shape/types (no coercion). */
+export function normalizeHermesSession(raw, { nowMs = Date.now() } = {}) {
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  if (typeof raw.id !== "string" || raw.id === "") return null;
+  const started = parseTs(raw.started_at), ended = parseTs(raw.ended_at), lastActive = parseTs(raw.last_active);
+  if (!started.ok || !ended.ok || !lastActive.ok) return null;
+  const messageCount = countOrZero(raw.message_count), toolCallCount = countOrZero(raw.tool_call_count);
+  const inputTokens = countOrZero(raw.input_tokens), outputTokens = countOrZero(raw.output_tokens);
+  if (!messageCount.ok || !toolCallCount.ok || !inputTokens.ok || !outputTokens.ok) return null;
+  const source = optString(raw.source), model = optString(raw.model);
+  const title = optString(raw.title), endReason = optString(raw.end_reason);
+  if (!source.ok || !model.ok || !title.ok || !endReason.ok) return null;
+  const lastActiveMs = lastActive.ms ?? ended.ms ?? started.ms;
+  const isEnded = ended.ms != null || (endReason.s != null && endReason.s.length > 0);
+  const iso = (ms) => (ms == null ? null : new Date(ms).toISOString());
+  return {
+    id: raw.id, source: source.s, model: model.s, title: title.s,
+    startedAt: iso(started.ms), endedAt: iso(ended.ms), lastActiveAt: iso(lastActiveMs),
+    messageCount: messageCount.n, toolCallCount: toolCallCount.n,
+    tokenCount: inputTokens.n + outputTokens.n,
+    active: !isEnded && lastActiveMs != null && (nowMs - lastActiveMs) >= 0 && (nowMs - lastActiveMs) <= HERMES_ACTIVE_WINDOW_MS
+  };
+}
+
+/**
+ * Read-only Hermes session activity via official local API.
+ * Sequence: GET /v1/capabilities → GET /api/sessions (never CLI / state.db).
+ */
+export async function loadHermesActivity({
+  env = process.env,
+  baseUrl = env.KAIRO_HERMES_API_URL ?? DEFAULT_HERMES_API_URL,
+  apiKey = env.KAIRO_HERMES_API_KEY ?? null,
+  limit = HERMES_ACTIVITY_LIMIT_DEFAULT,
+  timeoutMs = HERMES_ACTIVITY_TIMEOUT_MS,
+  nowMs = Date.now(),
+  fetchImpl = globalThis.fetch
+} = {}) {
+  const checked = assertHermesLoopbackUrl(baseUrl);
+  if (!checked.ok) return opaque("incompatible", [`hermes baseUrl rejected: ${checked.reason}`]);
+  const origin = checked.url;
+  const capped = clampLimit(limit);
+  const key = apiKey ? String(apiKey) : null;
+
+  const capsRes = await hermesGet(`${origin}/v1/capabilities`, { apiKey: key, timeoutMs, fetchImpl });
+  const capsFail = classifyTransport(capsRes);
+  if (capsFail) return opaque(capsFail, [`hermes capabilities ${capsFail}`], origin);
+  if (!capsRes.ok || !isJson(capsRes.data)
+    || capsRes.data.platform !== "hermes-agent"
+    || !capabilitiesAdvertiseSessionsList(capsRes.data)) {
+    return opaque("incompatible", ["hermes session capabilities unsupported"], origin);
+  }
+
+  const qs = new URLSearchParams({ limit: String(capped), offset: "0", include_children: "false" });
+  const sessionsRes = await hermesGet(`${origin}/api/sessions?${qs}`, { apiKey: key, timeoutMs, fetchImpl });
+  const sessFail = classifyTransport(sessionsRes);
+  if (sessFail) return opaque(sessFail, [`hermes sessions ${sessFail}`], origin);
+  if (!sessionsRes.ok) return opaque("error", [`hermes sessions http ${sessionsRes.status}`], origin);
+  const payload = sessionsRes.data;
+  if (!isJson(payload) || payload.object !== "list" || !Array.isArray(payload.data)) {
+    return opaque("incompatible", ["hermes sessions schema unknown"], origin);
+  }
+
+  const sessions = [];
+  for (const row of payload.data) {
+    const session = normalizeHermesSession(row, { nowMs });
+    if (session == null) return opaque("incompatible", ["hermes session row invalid"], origin);
+    sessions.push(session);
+  }
+  sessions.sort((a, b) => (Date.parse(b.lastActiveAt ?? "") || 0) - (Date.parse(a.lastActiveAt ?? "") || 0)
+    || String(a.id).localeCompare(String(b.id)));
+
+  const hasMore = typeof payload.has_more === "boolean" ? payload.has_more : sessions.length >= capped;
+
+  return out({
+    state: "available", error: null, diagnostics: [], baseUrl: origin, sessions,
+    aggregates: {
+      returnedCount: sessions.length,
+      activeCount: sessions.filter((s) => s.active).length,
+      endedCount: sessions.filter((s) => s.endedAt != null).length,
+      hasMore, lastActiveAt: sessions[0]?.lastActiveAt ?? null
+    }
+  });
+}