@cohortapp/agent-sdk 2.3.0

package/lib/org/activity.mjs

@@ -0,0 +1,211 @@
+/**
+ * lib/org/activity.mjs — peer-activity lookup over the status-bearing directory.
+ *
+ * THE PAYOFF of the telemetry spine: each agent now rides the SHARED STATUS
+ * SNAPSHOT on its presence beat (lib/telemetry/collect → mesh → server), so the
+ * org directory read carries every peer's latest status. This module turns that
+ * directory into the human question "who is doing what right now" — and the
+ * focused "what is <person> doing".
+ *
+ * Read-only and fail-open (mirrors the rest of lib/org): if the org is disabled or
+ * unreachable, `teamActivity` returns an empty, well-formed result and never
+ * throws. It NEVER decides ACL or filters peers — it renders what the directory
+ * read returned.
+ *
+ * Two surfaces:
+ *   - teamActivity({ cfg })          → { enabled, peers:[…], summary, ts } where
+ *                                       each peer is { id, name, title, state,
+ *                                       activity, subAgentsRunning, alerts,
+ *                                       machine, lastSeen, online }.
+ *   - whatIsDoing(slug, { cfg })     → the one peer (or { found:false }).
+ *
+ * The directory client is injectable (`deps.fetchDirectory`) so tests are
+ * hermetic; by default it uses lib/org/client.fetchDirectory.
+ *
+ * G16 (zero-LLM-in-the-coordination-loop): pure read + summarize. ZERO LLM calls.
+ *
+ * @module lib/org/activity
+ */
+
+"use strict";
+
+import * as defaultClient from "./client.mjs";
+
+/** A peer is "online" if its latest status timestamp is within this window. */
+const DEFAULT_ONLINE_WINDOW_MS = 2 * 60 * 1000; // 2 min (~4 missed 30s beats)
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+function nowMsFrom(now) {
+  if (typeof now === "function") { const v = Number(now()); return Number.isFinite(v) ? v : Date.now(); }
+  if (Number.isFinite(now)) return Number(now);
+  return Date.now();
+}
+
+/** Extract the status snapshot a directory entry carries, tolerating shapes. */
+function entryStatus(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  // The server may attach the snapshot as `status` (the snapshot object) or the
+  // legacy `status` string; only treat an object as the snapshot.
+  if (entry.status && typeof entry.status === "object") return entry.status;
+  if (entry.latestStatus && typeof entry.latestStatus === "object") return entry.latestStatus;
+  return null;
+}
+
+/** Human "Xs"/"Xm"/"Xh"/"Xd" age, or "never" for an unknown timestamp. */
+function ageLabel(iso, nowMs) {
+  const ms = nowMs - Date.parse(iso);
+  if (!Number.isFinite(ms) || ms < 0) return "just now";
+  const s = Math.round(ms / 1000);
+  if (s < 45) return "just now";
+  const m = Math.round(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  if (h < 48) return `${h}h ago`;
+  return `${Math.round(h / 24)}d ago`;
+}
+
+/**
+ * Normalise one directory entry into a peer-activity row. Pure. A peer without a
+ * status snapshot still renders (state "unknown", activity "no status reported")
+ * so the absence is visible rather than silent.
+ */
+export function normalizePeer(entry, o = {}) {
+  const nowMs = nowMsFrom(o.now);
+  const onlineWindowMs = Number.isFinite(o.onlineWindowMs) ? o.onlineWindowMs : DEFAULT_ONLINE_WINDOW_MS;
+  const e = entry && typeof entry === "object" ? entry : {};
+  const st = entryStatus(e);
+
+  const id = String(e.id || e.slug || e.repo || e.name || "").toLowerCase();
+  const name = e.name || e.displayName || e.fullName || id;
+  const title = e.title || (e.archetype && e.archetype.label) || "";
+
+  const row = {
+    id,
+    name,
+    title,
+    state: "unknown",
+    activity: "no status reported",
+    subAgentsRunning: 0,
+    session: null,
+    machine: null,
+    claudeAuth: "unknown",
+    alerts: [],
+    ts: null,
+    lastSeen: "never",
+    online: false,
+  };
+
+  if (st) {
+    row.state = typeof st.state === "string" ? st.state : "unknown";
+    row.activity = typeof st.activity === "string" && st.activity ? st.activity : "idle";
+    row.subAgentsRunning = Number.isFinite(st.subAgentsRunning) ? st.subAgentsRunning : 0;
+    row.session = st.session || null;
+    row.machine = st.machine && typeof st.machine === "object" ? st.machine : null;
+    row.claudeAuth = typeof st.claudeAuth === "string" ? st.claudeAuth : "unknown";
+    row.alerts = Array.isArray(st.alerts) ? st.alerts : [];
+    row.ts = st.ts || null;
+    row.lastSeen = ageLabel(st.ts, nowMs);
+    const age = nowMs - Date.parse(st.ts || 0);
+    row.online = Number.isFinite(age) && age >= 0 && age <= onlineWindowMs && st.state !== "offline";
+  }
+  return row;
+}
+
+/** Compose a one-line human summary for a peer row. House voice: plain prose. */
+function peerLine(row) {
+  const who = row.name || row.id;
+  const what = row.online ? row.activity : (row.state === "unknown" ? "no status reported" : `${row.state} (last seen ${row.lastSeen})`);
+  const crit = (row.alerts || []).filter((a) => a && a.severity === "critical");
+  const flag = crit.length ? ` — ALERT: ${crit.map((a) => a.detail || a.id).join("; ")}` : "";
+  return `${who}: ${what}${flag}`;
+}
+
+/** Build the multi-line fleet summary (online peers first, then by name). */
+function buildSummary(peers) {
+  if (!Array.isArray(peers) || peers.length === 0) return "No peers in the directory.";
+  const sorted = peers.slice().sort((a, b) => {
+    if (a.online !== b.online) return a.online ? -1 : 1;
+    return (a.name || a.id) < (b.name || b.id) ? -1 : 1;
+  });
+  return sorted.map(peerLine).join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// public surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Summarise "who is doing what right now" across the org directory.
+ *
+ * @param {object} o
+ * @param {object} o.cfg                       agent/collective config (org.cohort.*)
+ * @param {Function} [o.fetchImpl]            injected fetch (passed to the client)
+ * @param {Function} [o.fetchDirectory]       injected directory reader (tests)
+ * @param {object}  [o.client]                injected org client (defaults to lib/org/client)
+ * @param {number|Function} [o.now]           clock
+ * @param {number}  [o.onlineWindowMs]        online freshness window
+ * @param {string}  [o.excludeId]             omit this id (usually self) from peers
+ * @returns {Promise<{enabled:boolean, peers:object[], summary:string, ts:string}>}
+ */
+export async function teamActivity(o = {}) {
+  const nowMs = nowMsFrom(o.now);
+  const result = { enabled: false, peers: [], summary: "Org integration is disabled — no team activity available.", ts: new Date(nowMs).toISOString() };
+  try {
+    const cfg = o.cfg || {};
+    const client = o.client || defaultClient;
+    const enabled = (() => { try { return client.isEnabled(cfg); } catch { return false; } })();
+    result.enabled = enabled;
+    if (!enabled) return result;
+
+    let directory = [];
+    try {
+      if (typeof o.fetchDirectory === "function") directory = await o.fetchDirectory({ cfg, fetchImpl: o.fetchImpl });
+      else directory = await client.fetchDirectory({ cfg, fetchImpl: o.fetchImpl });
+    } catch { directory = []; }
+    directory = Array.isArray(directory) ? directory : [];
+
+    const exclude = o.excludeId ? String(o.excludeId).toLowerCase() : "";
+    const peers = directory
+      .map((e) => normalizePeer(e, { now: nowMs, onlineWindowMs: o.onlineWindowMs }))
+      .filter((p) => p.id && p.id !== exclude);
+
+    result.peers = peers;
+    result.summary = peers.length ? buildSummary(peers) : "No peers reporting status yet.";
+    return result;
+  } catch {
+    return result;
+  }
+}
+
+/**
+ * What is one specific peer doing right now? Resolves by id/slug, then by a
+ * case-insensitive name/title contains-match. Read-only, fail-open.
+ *
+ * @param {string} slug   the agent id/slug, or a name fragment
+ * @param {object} o      same options as teamActivity
+ * @returns {Promise<{found:boolean, peer?:object, line?:string}>}
+ */
+export async function whatIsDoing(slug, o = {}) {
+  const out = { found: false };
+  try {
+    const want = String(slug || "").trim().toLowerCase();
+    if (!want) return out;
+    const team = await teamActivity({ ...o, excludeId: undefined });
+    const peers = Array.isArray(team.peers) ? team.peers : [];
+    // Exact id first, then name/title contains.
+    let peer = peers.find((p) => p.id === want);
+    if (!peer) peer = peers.find((p) => String(p.name || "").toLowerCase() === want);
+    if (!peer) peer = peers.find((p) => String(p.name || "").toLowerCase().includes(want) || String(p.title || "").toLowerCase().includes(want));
+    if (!peer) return out;
+    return { found: true, peer, line: peerLine(peer) };
+  } catch {
+    return out;
+  }
+}
+
+export const _internals = { normalizePeer, entryStatus, ageLabel, peerLine, buildSummary };
+
+export default { teamActivity, whatIsDoing };

package/lib/org/activity.test.mjs

@@ -0,0 +1,134 @@
+/**
+ * activity.test.mjs — peer-activity lookup over the status-bearing directory.
+ *
+ * Hermetic: injects a fake org client (isEnabled + fetchDirectory) returning a
+ * directory whose entries carry status snapshots. Asserts teamActivity summarizes
+ * peers, whatIsDoing resolves by id/name, fail-open when disabled/unreachable, and
+ * peers without a snapshot still render.
+ *
+ * Run: node --test lib/org/activity.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { teamActivity, whatIsDoing, _internals } from "./activity.mjs";
+
+const NOW = Date.parse("2026-06-12T12:00:00Z");
+const FRESH = "2026-06-12T11:59:50Z"; // 10s ago → online
+const STALE = "2026-06-12T11:50:00Z"; // 10m ago → not online
+
+function snap(over = {}) {
+  return {
+    state: "busy", activity: "session: inbox", subAgentsRunning: 1,
+    session: { id: "s1", taskClass: "inbox" }, machine: { loadavg: [1, 1, 1], memUsedPct: 40 },
+    claudeAuth: "ok", alerts: [], ts: FRESH, ...over,
+  };
+}
+
+function fakeClient(directory, enabled = true) {
+  return {
+    isEnabled: () => enabled,
+    fetchDirectory: async () => directory,
+  };
+}
+
+const cfg = { org: { cohort: { enabled: true, base: "https://x", token: "t" } } };
+
+// ---------------------------------------------------------------------------
+
+test("teamActivity summarizes peers from the directory", async () => {
+  const directory = [
+    { id: "robin-ai", name: "Robin", title: "Engineer", status: snap() },
+    { id: "sam-ai", name: "Sam", title: "CFO", status: snap({ state: "idle", activity: "idle", subAgentsRunning: 0, ts: FRESH }) },
+  ];
+  const team = await teamActivity({ cfg, client: fakeClient(directory), now: NOW });
+  assert.equal(team.enabled, true);
+  assert.equal(team.peers.length, 2);
+  const robin = team.peers.find((p) => p.id === "robin-ai");
+  assert.equal(robin.state, "busy");
+  assert.equal(robin.activity, "session: inbox");
+  assert.equal(robin.online, true);
+  assert.match(team.summary, /Robin/);
+  assert.match(team.summary, /Sam/);
+});
+
+test("teamActivity: a peer with no snapshot renders as unknown / no status", async () => {
+  const directory = [{ id: "mia-ai", name: "Mia", title: "Legal" }]; // no status
+  const team = await teamActivity({ cfg, client: fakeClient(directory), now: NOW });
+  const mia = team.peers[0];
+  assert.equal(mia.state, "unknown");
+  assert.equal(mia.activity, "no status reported");
+  assert.equal(mia.online, false);
+});
+
+test("teamActivity: stale snapshot → offline-ish (not online), lastSeen rendered", async () => {
+  const directory = [{ id: "old-ai", name: "Old", status: snap({ ts: STALE }) }];
+  const team = await teamActivity({ cfg, client: fakeClient(directory), now: NOW });
+  assert.equal(team.peers[0].online, false);
+  assert.match(team.peers[0].lastSeen, /m ago|h ago/);
+});
+
+test("teamActivity: a critical alert surfaces in the peer line", async () => {
+  const directory = [{ id: "down-ai", name: "Down", status: snap({ state: "error", claudeAuth: "relogin_required", alerts: [{ id: "claude_relogin_required", severity: "critical", kind: "auth", detail: "claude re-login required" }] }) }];
+  const team = await teamActivity({ cfg, client: fakeClient(directory), now: NOW });
+  assert.match(team.summary, /ALERT/);
+  assert.match(team.summary, /re-login/);
+});
+
+test("teamActivity: disabled org → fail-open empty result, never throws", async () => {
+  const team = await teamActivity({ cfg, client: fakeClient([], false), now: NOW });
+  assert.equal(team.enabled, false);
+  assert.deepEqual(team.peers, []);
+  assert.match(team.summary, /disabled/);
+});
+
+test("teamActivity: unreachable directory (throwing fetch) → empty peers, no throw", async () => {
+  const client = { isEnabled: () => true, fetchDirectory: async () => { throw new Error("ECONNREFUSED"); } };
+  let team;
+  await assert.doesNotReject(async () => { team = await teamActivity({ cfg, client, now: NOW }); });
+  assert.equal(team.enabled, true);
+  assert.deepEqual(team.peers, []);
+});
+
+test("teamActivity: excludeId omits self", async () => {
+  const directory = [
+    { id: "self-ai", name: "Self", status: snap() },
+    { id: "peer-ai", name: "Peer", status: snap() },
+  ];
+  const team = await teamActivity({ cfg, client: fakeClient(directory), now: NOW, excludeId: "self-ai" });
+  assert.deepEqual(team.peers.map((p) => p.id), ["peer-ai"]);
+});
+
+test("whatIsDoing resolves by id, then by name/title fragment", async () => {
+  const directory = [
+    { id: "robin-ai", name: "Robin", title: "Senior Engineer", status: snap({ activity: "writing tests" }) },
+  ];
+  const opts = { cfg, client: fakeClient(directory), now: NOW };
+
+  const byId = await whatIsDoing("robin-ai", opts);
+  assert.equal(byId.found, true);
+  assert.match(byId.line, /writing tests/);
+
+  const byName = await whatIsDoing("robin", opts);
+  assert.equal(byName.found, true);
+
+  const byTitle = await whatIsDoing("engineer", opts);
+  assert.equal(byTitle.found, true);
+
+  const miss = await whatIsDoing("nobody", opts);
+  assert.equal(miss.found, false);
+});
+
+test("normalizePeer is a pure mapper tolerant of shapes", () => {
+  const row = _internals.normalizePeer({ id: "X-AI", displayName: "Ex", status: snap({ subAgentsRunning: 3 }) }, { now: NOW });
+  assert.equal(row.id, "x-ai");
+  assert.equal(row.name, "Ex");
+  assert.equal(row.subAgentsRunning, 3);
+  assert.equal(row.online, true);
+  // garbage → safe defaults
+  const empty = _internals.normalizePeer(null, { now: NOW });
+  assert.equal(empty.state, "unknown");
+  assert.equal(empty.online, false);
+});