@cohortapp/agent-sdk 2.5.1 → 2.6.0

package/lib/org/engagement-ledger.mjs

@@ -0,0 +1,376 @@
+/**
+ * lib/org/engagement-ledger.mjs — the record of who this agent pulled in, why,
+ * and what it deliberately did NOT do.
+ *
+ * Engagement is the one agent behaviour whose failure modes are symmetric and
+ * both bad: engage nobody when someone is blocked and the work dies silently;
+ * engage everybody and you have built a spam bot with a directory. The judgement
+ * that separates them lives in `engagement.mjs`. This module is its memory —
+ * without it the judgement is stateless, and a stateless judgement re-asks the
+ * same person the same question every time the same work comes round.
+ *
+ * ── WHAT GETS WRITTEN ──
+ * EVERY decision, engaged or not. An "I decided nobody needs to be involved"
+ * row is the entire point: it is the difference between a considered silence and
+ * a bug. `state/org/engagement.jsonl`, append-only, one JSON object per line:
+ *
+ *   {
+ *     at, atMs,                     when
+ *     workId, reasonCode, trigger,  what and why
+ *     dedupeKey,                    (workId, reasonCode, targets) identity
+ *     engaged: bool,
+ *     outcome: "engaged" | "none" | "duplicate" | "rate_limited"
+ *            | "unroutable" | "send_blocked" | "send_failed",
+ *     surface, channelId, roomCreated: bool,
+ *     targets: [memberId],
+ *     why: [ audit lines ],
+ *     resolvedAtMs: null | number   set when the ask came back answered
+ *   }
+ *
+ * ── THE DEDUPE IDENTITY ──
+ * `(workId, reasonCode, sorted targetIds)`. Deliberately NOT the message text:
+ * two differently-worded pings about the same blocker to the same person are the
+ * same ping, and text-keyed dedupe is exactly the bug that left 49 duplicate
+ * `machine_mem_high` alert rows open in production because the detail string
+ * carried a live measurement. Key on the identity of the ask, never on its
+ * rendering.
+ *
+ * ── FAIL-OPEN, BUT NOT ON THE GUARDRAIL ──
+ * Reads fail open to `[]` (an unreadable ledger must not wedge the agent). The
+ * consequence is deliberate and worth naming: with no history, dedupe cannot
+ * fire and the caps read as unspent, so a broken ledger biases towards sending.
+ * That is the right bias for a system whose owner's actual complaint is silence
+ * — but the caller is told (`degraded: ["ledger_unreadable"]`) rather than left
+ * to assume the guardrails ran.
+ *
+ * Node builtins only. ESM. Every clock and path injectable.
+ *
+ * @module lib/org/engagement-ledger
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+
+import { resolveAgentRoot } from "../agent-root.mjs";
+import { appendJsonl } from "../fs-atomic.mjs";
+
+/** Where the record lives, relative to the agent root. */
+export const ENGAGEMENT_LEDGER_REL = "state/org/engagement.jsonl";
+
+const HOUR_MS = 60 * 60 * 1000;
+const DAY_MS = 24 * HOUR_MS;
+
+/**
+ * The caps, and why each number is what it is.
+ *
+ * These are not arbitrary. Each one answers "at what point does one more
+ * message stop carrying information and start carrying noise?" — and each is
+ * env-overridable because the right answer differs between a two-person startup
+ * and a fifty-seat org.
+ */
+export const DEFAULT_LIMITS = Object.freeze({
+  /**
+   * 3/day/person. A colleague who hears from an agent three times in a day is
+   * being kept informed; the fourth time they start filtering it, and a filtered
+   * channel is a dead channel. This is the cap that protects the CHANNEL, not
+   * the person's time.
+   */
+  perTargetPerDay: num(process.env.ENGAGE_PER_TARGET_PER_DAY, 3),
+  /**
+   * 5 total per piece of work, ever. Work that needs a sixth engagement is not
+   * blocked on a person, it is badly specified — and the honest move then is to
+   * escalate the SHAPE of the work, not to keep pinging.
+   */
+  perWorkTotal: num(process.env.ENGAGE_PER_WORK_TOTAL, 5),
+  /**
+   * 10/hour across the whole agent. The blast-radius cap: whatever goes wrong in
+   * the judgement, one seat cannot generate more than ten pings in an hour.
+   * Sized so a genuinely bad hour (several parallel blockages) still fits, and a
+   * runaway loop does not.
+   */
+  globalPerHour: num(process.env.ENGAGE_GLOBAL_PER_HOUR, 10),
+  /**
+   * 2 new rooms/day. A room is the most expensive thing an agent can create —
+   * persistent, visible to everyone in it, and impossible to un-see. Two a day
+   * is "this genuinely needed its own space"; five a day is an agent that has
+   * confused activity with progress.
+   */
+  newRoomsPerDay: num(process.env.ENGAGE_NEW_ROOMS_PER_DAY, 2),
+  /**
+   * 6h before the same ask may be repeated to the same people. Under that, a
+   * repeat is a nag; over it, silence starts to look like the agent forgot.
+   * Only applies while the earlier ask is UNRESOLVED — an answered ask is not
+   * duplicated by a new one, it is superseded.
+   */
+  reengageAfterMs: num(process.env.ENGAGE_REENGAGE_AFTER_MS, 6 * HOUR_MS),
+});
+
+function num(v, dflt) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+
+function ledgerPath(o = {}) {
+  if (o.path) return o.path;
+  return join(resolveAgentRoot(o.agentRoot), ENGAGEMENT_LEDGER_REL);
+}
+
+/**
+ * The identity of an ask: who is being asked, about what, for which reason.
+ * Stable across rewordings, retries and process restarts.
+ *
+ * @param {{workId?:string, reasonCode?:string, targets?:Array<string|{memberId:string}>}} o
+ * @returns {string} 16 hex chars
+ */
+export function dedupeKeyFor(o = {}) {
+  const targets = (Array.isArray(o.targets) ? o.targets : [])
+    .map((t) => String(t && typeof t === "object" ? t.memberId : t || "").trim())
+    .filter(Boolean)
+    .sort();
+  const raw = [String(o.workId || ""), String(o.reasonCode || ""), targets.join(",")].join("|");
+  return createHash("sha1").update(raw).digest("hex").slice(0, 16);
+}
+
+/**
+ * Read the ledger. Newest last (append order). Never throws.
+ *
+ * @param {object} [o] { agentRoot, path, sinceMs, nowMs, limit }
+ * @returns {{rows:object[], degraded:string[]}}
+ */
+export function loadEngagements(o = {}) {
+  const path = ledgerPath(o);
+  if (!existsSync(path)) return { rows: [], degraded: [] };
+  let text;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch {
+    // Named, not swallowed — the caller surfaces it so a wedged guardrail is
+    // visible rather than merely permissive.
+    return { rows: [], degraded: ["ledger_unreadable"] };
+  }
+  const rows = [];
+  let bad = 0;
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    try {
+      const row = JSON.parse(t);
+      if (row && typeof row === "object") rows.push(row);
+    } catch {
+      bad += 1; // a torn line is one lost record, not a lost ledger
+    }
+  }
+  const sinceMs = Number.isFinite(o.sinceMs) ? o.sinceMs : null;
+  const kept = sinceMs == null ? rows : rows.filter((r) => Number(r.atMs) >= sinceMs);
+  const limited = Number.isFinite(o.limit) ? kept.slice(-o.limit) : kept;
+  return { rows: limited, degraded: bad ? [`ledger_torn_lines:${bad}`] : [] };
+}
+
+/**
+ * Append one decision — engaged or not.
+ * @param {object} record
+ * @param {object} [o] { agentRoot, path, nowMs }
+ * @returns {{ok:boolean, path:string}}
+ */
+export function appendEngagement(record, o = {}) {
+  const path = ledgerPath(o);
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const row = {
+    at: new Date(nowMs).toISOString(),
+    atMs: nowMs,
+    workId: record && record.workId ? String(record.workId) : "",
+    trigger: (record && record.trigger) || null,
+    reasonCode: (record && record.reasonCode) || null,
+    reason: (record && record.reason) || null,
+    dedupeKey: (record && record.dedupeKey) || null,
+    engaged: !!(record && record.engaged),
+    outcome: (record && record.outcome) || (record && record.engaged ? "engaged" : "none"),
+    surface: (record && record.surface) || "none",
+    channelId: (record && record.channelId) || null,
+    roomCreated: !!(record && record.roomCreated),
+    targets: (Array.isArray(record && record.targets) ? record.targets : []).map((t) =>
+      String(t && typeof t === "object" ? t.memberId : t),
+    ),
+    why: Array.isArray(record && record.why) ? record.why.map(String) : [],
+    resolvedAtMs: null,
+  };
+  const ok = appendJsonl(path, row);
+  return { ok, path, row };
+}
+
+/**
+ * Mark an ask answered, so the 6h re-engage clock stops applying to it. Recorded
+ * as its own append (the file is append-only; the newest row for a dedupeKey
+ * wins) rather than a rewrite, so a crash mid-update cannot corrupt history.
+ *
+ * @param {string} dedupeKey
+ * @param {object} [o] { agentRoot, path, nowMs, by }
+ */
+export function markResolved(dedupeKey, o = {}) {
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const ok = appendJsonl(ledgerPath(o), {
+    at: new Date(nowMs).toISOString(),
+    atMs: nowMs,
+    dedupeKey: String(dedupeKey || ""),
+    outcome: "resolved",
+    engaged: false,
+    resolvedAtMs: nowMs,
+    resolvedBy: o.by ? String(o.by) : null,
+    targets: [],
+    why: [],
+  });
+  return { ok };
+}
+
+/**
+ * Has this exact ask already gone out, and is it still outstanding?
+ * PURE over the rows the caller loaded.
+ *
+ * @param {object[]} rows
+ * @param {string} dedupeKey
+ * @param {number} nowMs
+ * @param {number} reengageAfterMs
+ * @returns {{duplicate:boolean, lastAtMs:number|null, resolved:boolean, ageMs:number|null}}
+ */
+export function findOutstanding(rows, dedupeKey, nowMs, reengageAfterMs) {
+  const key = String(dedupeKey || "");
+  if (!key) return { duplicate: false, lastAtMs: null, resolved: false, ageMs: null, sends: 0 };
+  let lastSent = null;
+  let resolvedAfter = false;
+  // How many times this exact ask has actually gone out. The dedupe key is
+  // deliberately timeless — that is what makes the 6h window enforceable — so
+  // something else has to distinguish the FIRST ask from the re-ask at the far
+  // side of that window. This is that something: hq de-dupes a send on
+  // (org, channel, clientMsgId) and returns the existing message verbatim, so a
+  // re-ask carrying the first ask's message id posts nothing at all while every
+  // local signal reports it delivered. The count is the attempt ordinal.
+  let sends = 0;
+  for (const r of Array.isArray(rows) ? rows : []) {
+    if (String(r.dedupeKey || "") !== key) continue;
+    if (r.outcome === "resolved") {
+      resolvedAfter = true;
+      lastSent = null; // an answer supersedes everything before it
+      continue;
+    }
+    if (r.engaged === true) {
+      lastSent = Number(r.atMs) || null;
+      resolvedAfter = false;
+      sends += 1;
+    }
+  }
+  if (lastSent == null) return { duplicate: false, lastAtMs: null, resolved: resolvedAfter, ageMs: null, sends };
+  const ageMs = nowMs - lastSent;
+  return { duplicate: ageMs < reengageAfterMs, lastAtMs: lastSent, resolved: false, ageMs, sends };
+}
+
+/**
+ * Apply every cap. PURE over the loaded rows — no clock, no disk, no network —
+ * so the whole guardrail set is testable by handing it an array.
+ *
+ * Order matters and is deliberate: DUPLICATE first, because "you already asked
+ * this" is a better explanation than "you are over quota", and a duplicate must
+ * never consume a rate-limit slot.
+ *
+ * @param {object} o {
+ *   rows, nowMs, dedupeKey, workId, targets:[memberId], createsRoom:boolean, limits?
+ * }
+ * @returns {{allowed:boolean, code:string|null, detail:string|null, counts:object}}
+ */
+export function checkGuardrails(o = {}) {
+  const limits = { ...DEFAULT_LIMITS, ...(o.limits || {}) };
+  const rows = Array.isArray(o.rows) ? o.rows : [];
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : Date.now();
+  const targets = (Array.isArray(o.targets) ? o.targets : [])
+    .map((t) => String(t && typeof t === "object" ? t.memberId : t || ""))
+    .filter(Boolean);
+
+  const sent = rows.filter((r) => r.engaged === true);
+  const dayAgo = nowMs - DAY_MS;
+  const hourAgo = nowMs - HOUR_MS;
+
+  const counts = {
+    globalLastHour: sent.filter((r) => Number(r.atMs) >= hourAgo).length,
+    roomsLastDay: sent.filter((r) => Number(r.atMs) >= dayAgo && r.roomCreated === true).length,
+    perTargetLastDay: {},
+    thisWorkTotal: sent.filter((r) => String(r.workId || "") === String(o.workId || "")).length,
+  };
+  for (const t of targets) {
+    counts.perTargetLastDay[t] = sent.filter(
+      (r) => Number(r.atMs) >= dayAgo && Array.isArray(r.targets) && r.targets.includes(t),
+    ).length;
+  }
+
+  // 1. Already asked, still unanswered.
+  const dup = findOutstanding(rows, o.dedupeKey, nowMs, limits.reengageAfterMs);
+  if (dup.duplicate) {
+    const mins = Math.round(dup.ageMs / 60000);
+    return {
+      allowed: false,
+      code: "already_engaged",
+      detail: `the same ask went to the same people ${mins}m ago and has not been answered; re-ask allowed after ${Math.round(limits.reengageAfterMs / 60000)}m`,
+      counts,
+    };
+  }
+
+  // 2. Per-person daily cap.
+  for (const t of targets) {
+    if (counts.perTargetLastDay[t] >= limits.perTargetPerDay) {
+      return {
+        allowed: false,
+        code: "rate_limited_target",
+        detail: `${t} has already been engaged ${counts.perTargetLastDay[t]}× in the last 24h (cap ${limits.perTargetPerDay})`,
+        counts,
+      };
+    }
+  }
+
+  // 3. Per-work cap.
+  if (o.workId && counts.thisWorkTotal >= limits.perWorkTotal) {
+    return {
+      allowed: false,
+      code: "rate_limited_work",
+      detail: `work ${o.workId} has already generated ${counts.thisWorkTotal} engagements (cap ${limits.perWorkTotal}) — the work is mis-specified, not blocked`,
+      counts,
+    };
+  }
+
+  // 4. Global hourly blast radius.
+  if (counts.globalLastHour >= limits.globalPerHour) {
+    return {
+      allowed: false,
+      code: "rate_limited_global",
+      detail: `${counts.globalLastHour} engagements in the last hour (cap ${limits.globalPerHour})`,
+      counts,
+    };
+  }
+
+  // 5. Room creation cap — only consulted when this decision would make one.
+  if (o.createsRoom && counts.roomsLastDay >= limits.newRoomsPerDay) {
+    return {
+      allowed: false,
+      code: "rate_limited_rooms",
+      detail: `${counts.roomsLastDay} new rooms already created today (cap ${limits.newRoomsPerDay})`,
+      counts,
+    };
+  }
+
+  // `attempt` is the ordinal of the send this permission authorises: 1 for the
+  // first ask, 2 for the re-ask once the window reopens. The caller must fold it
+  // into the outbound message id — see findOutstanding for why a timeless dedupe
+  // key alone turns a re-ask into a no-op that reports success.
+  return { allowed: true, code: null, detail: null, counts, attempt: (dup.sends || 0) + 1 };
+}
+
+export default {
+  ENGAGEMENT_LEDGER_REL,
+  DEFAULT_LIMITS,
+  dedupeKeyFor,
+  loadEngagements,
+  appendEngagement,
+  markResolved,
+  findOutstanding,
+  checkGuardrails,
+};

package/lib/org/engagement-ledger.test.mjs

@@ -0,0 +1,112 @@
+/**
+ * engagement-ledger.test.mjs — the on-disk mechanics of the engagement record.
+ * Run: node --test lib/org/engagement-ledger.test.mjs
+ */
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, writeFileSync, chmodSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  appendEngagement,
+  loadEngagements,
+  markResolved,
+  findOutstanding,
+  dedupeKeyFor,
+  ENGAGEMENT_LEDGER_REL,
+} from "./engagement-ledger.mjs";
+
+const NOW = Date.parse("2026-08-13T12:00:00.000Z");
+const HOUR = 3600_000;
+const root = () => mkdtempSync(join(tmpdir(), "engledger-"));
+
+test("an append round-trips, and the agent root resolves to the documented path", () => {
+  const r = root();
+  const res = appendEngagement(
+    { workId: "W-1", reasonCode: "blocked:access", dedupeKey: "k1", engaged: true, surface: "dm", targets: [{ memberId: "M-2" }], why: ["because"] },
+    { agentRoot: r, nowMs: NOW },
+  );
+  assert.equal(res.ok, true);
+  assert.equal(res.path, join(r, ENGAGEMENT_LEDGER_REL));
+
+  const { rows } = loadEngagements({ agentRoot: r });
+  assert.equal(rows.length, 1);
+  assert.deepEqual(rows[0].targets, ["M-2"], "target objects are flattened to ids on disk");
+  assert.equal(rows[0].at, new Date(NOW).toISOString());
+  assert.equal(rows[0].outcome, "engaged");
+  assert.deepEqual(rows[0].why, ["because"]);
+});
+
+test("a non-engagement is recorded just as loudly as an engagement", () => {
+  const r = root();
+  appendEngagement({ workId: "W-2", reasonCode: "self_contained", engaged: false, why: ["no trigger fired"] }, { agentRoot: r, nowMs: NOW });
+  const row = loadEngagements({ agentRoot: r }).rows[0];
+  assert.equal(row.engaged, false);
+  assert.equal(row.outcome, "none");
+  assert.equal(row.reasonCode, "self_contained");
+});
+
+test("a torn line loses one record, not the ledger, and the loss is reported", () => {
+  const r = root();
+  const p = join(r, ENGAGEMENT_LEDGER_REL);
+  appendEngagement({ workId: "A", dedupeKey: "k", engaged: true }, { agentRoot: r, nowMs: NOW });
+  writeFileSync(p, readFileSync(p, "utf8") + '{"workId":"B",trunca\n');
+  appendEngagement({ workId: "C", dedupeKey: "k", engaged: true }, { agentRoot: r, nowMs: NOW + 1000 });
+
+  const { rows, degraded } = loadEngagements({ agentRoot: r });
+  assert.deepEqual(rows.map((x) => x.workId), ["A", "C"]);
+  assert.deepEqual(degraded, ["ledger_torn_lines:1"]);
+});
+
+test("an unreadable ledger is reported, not silently treated as empty", () => {
+  const r = root();
+  appendEngagement({ workId: "A", engaged: true }, { agentRoot: r, nowMs: NOW });
+  const p = join(r, ENGAGEMENT_LEDGER_REL);
+  chmodSync(p, 0o000);
+  try {
+    const { rows, degraded } = loadEngagements({ agentRoot: r });
+    // Root can read anything; skip the assertion rather than assert a falsehood.
+    if (degraded.length) {
+      assert.deepEqual(degraded, ["ledger_unreadable"]);
+      assert.deepEqual(rows, [], "biases towards sending — which is the right bias, but it must be visible");
+    }
+  } finally {
+    chmodSync(p, 0o600);
+  }
+});
+
+test("markResolved supersedes an outstanding ask without rewriting history", () => {
+  const r = root();
+  const key = dedupeKeyFor({ workId: "W-3", reasonCode: "blocked:decision", targets: ["M-2"] });
+  appendEngagement({ workId: "W-3", dedupeKey: key, engaged: true, targets: ["M-2"] }, { agentRoot: r, nowMs: NOW - HOUR });
+
+  let rows = loadEngagements({ agentRoot: r }).rows;
+  assert.equal(findOutstanding(rows, key, NOW, 6 * HOUR).duplicate, true);
+
+  markResolved(key, { agentRoot: r, nowMs: NOW - 60_000, by: "M-2" });
+  rows = loadEngagements({ agentRoot: r }).rows;
+  assert.equal(rows.length, 2, "append-only: nothing was rewritten");
+  const out = findOutstanding(rows, key, NOW, 6 * HOUR);
+  assert.equal(out.duplicate, false);
+  assert.equal(out.resolved, true);
+});
+
+test("the re-engage clock releases the ask once the window passes", () => {
+  const rows = [{ atMs: NOW - 7 * HOUR, dedupeKey: "k", engaged: true, targets: ["M-2"] }];
+  assert.equal(findOutstanding(rows, "k", NOW, 6 * HOUR).duplicate, false);
+  assert.equal(findOutstanding(rows, "k", NOW, 8 * HOUR).duplicate, true);
+});
+
+test("sinceMs trims the window without touching the file", () => {
+  const r = root();
+  appendEngagement({ workId: "old", engaged: true }, { agentRoot: r, nowMs: NOW - 48 * HOUR });
+  appendEngagement({ workId: "new", engaged: true }, { agentRoot: r, nowMs: NOW });
+  assert.deepEqual(
+    loadEngagements({ agentRoot: r, sinceMs: NOW - 24 * HOUR }).rows.map((x) => x.workId),
+    ["new"],
+  );
+  assert.equal(loadEngagements({ agentRoot: r }).rows.length, 2);
+});