@cohortapp/agent-sdk 2.14.0 → 2.16.0

package/lib/assurance/room-budget.mjs

@@ -0,0 +1,497 @@
+/**
+ * lib/assurance/room-budget.mjs — one interim per room per window, per seat.
+ *
+ * THE DEFECT THIS IS PART OF THE ANSWER TO
+ *
+ * The interim budget used to be per OBLIGATION and never per ROOM. Each inbound
+ * item opened its own debt with its own ack → progress → failure lifecycle, so
+ * N concurrent obligations in one channel emitted up to N acks, 2N progress
+ * pings and N failure notices — and nothing anywhere counted messages per room.
+ * Measured in `capital-formation` over 21 days: 9,187 messages from 8 agents,
+ * ~45 % exact duplicates, ~38 msg/h, and two independent timers narrating the
+ * same overlapping work at the SAME timestamp ("Still on this — 5 minutes in"
+ * beside "Still going — 15 minutes in"). Every individual decision was correct.
+ * The room was the thing nobody was counting.
+ *
+ * THE RULE, AND ITS HONEST SCOPE
+ *
+ *   At most ONE interim per (service, channel) per window — default 15 minutes,
+ *   `ASSURANCE_ROOM_INTERIM_WINDOW_MS` to change it — regardless of how many
+ *   obligations are open in that room, **for this agent seat**.
+ *
+ * THAT LAST CLAUSE IS LOAD-BEARING AND WAS ONCE MISSING FROM THIS HEADER.
+ * The ledger lives under `AGENT_DIR`, which is one agent's repo on one Mac
+ * mini. There is no shared store between seats — the fleet is N machines with
+ * no common filesystem — so the guarantee this module can actually make is
+ * per (seat, service, channel), not per (service, channel).
+ *
+ * The arithmetic that follows from that, stated rather than glossed, because a
+ * reader who believes "one room ⇒ one message" will mis-size the next change:
+ * the measured room had 8 seats in it, so this gate's ceiling there is
+ * 8 × (60/15) = 32 interims/hour. The measured content-free rate in that room
+ * was ~38 msg/h × 37.8 % ≈ 14/h. 32 > 14, so THIS GATE ALONE WOULD NOT HAVE
+ * BEEN THE BINDING CONSTRAINT on the measured data. What removed the measured
+ * traffic is the whole stack, and mostly the other three gates:
+ *
+ *   - the deleted progress branch          — 961 messages → 0, unconditionally;
+ *   - `sanitiseAckText`'s generic-opener
+ *     rejection ⇒ null ⇒ send nothing      — blocks the measured opening-ack
+ *                                            population outright;
+ *   - nothing at all before ACK_AFTER_MS
+ *     plus the per-obligation `interimSaid`
+ *     latch, inherited across retries       — one interim per ask, ever.
+ *
+ * This gate is the BACKSTOP that bounds what survives all of those: it is what
+ * keeps a single seat holding twenty concurrent asks in one channel from
+ * emitting twenty bespoke, individually-defensible holding lines. Sized
+ * correctly, described correctly, and not credited with the whole fix.
+ *
+ * WHAT THE BUDGET GOVERNS, AND WHAT IT DOES NOT
+ *
+ *   governed   — interims: the holding acknowledgement and the plan note. These
+ *                are courtesies. A room that has had one does not need another.
+ *   ungoverned — outcome messages: failure, stale, interrupted, and the
+ *                silent-success recovery. These carry information a human
+ *                cannot get any other way, and rate-limiting one re-creates the
+ *                original bug (a person who is never told their work died).
+ *
+ *                They are not ungoverned ENTIRELY, though: see
+ *                `claimRoomNotice` below, which suppresses a BYTE-IDENTICAL
+ *                repeat of one into the same room. That is a different
+ *                question from "has this room had enough" — a sentence
+ *                indistinguishable from one already on screen cannot tell a
+ *                reader which ask it is about, so the second copy carries no
+ *                information at all, only volume.
+ *
+ * SHAPE. The decisions are pure and take the ledger as an argument; the durable
+ * edges (`claimRoomInterim`, `claimRoomNotice`) are the only functions that
+ * touch disk, and their clock and filesystem are both injected. The default
+ * window is resolved by `roomInterimWindowMs(env)` — a function, called at the
+ * EDGE, not a constant captured at module load: a constant folded at import
+ * time means an operator who exports the env var after the first import gets
+ * the stale default with no error, and means a pure module read the
+ * environment on the way past.
+ *
+ * FAIL-OPEN DIRECTION, chosen deliberately. An unreadable or unwritable ledger
+ * ALLOWS the message and reports `degraded: true`. A JSON file that will not
+ * parse must never be the reason a waiting human hears nothing; the cost of
+ * that direction is bounded by every other gate still standing, and `degraded`
+ * makes the condition countable instead of silent.
+ *
+ * @module lib/assurance/room-budget
+ */
+
+"use strict";
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeJsonAtomic } from "../fs-atomic.mjs";
+
+const num = (v, d) => { const n = parseInt(v, 10); return Number.isFinite(n) ? n : d; };
+
+/**
+ * How long one interim buys a room's silence, absent an override.
+ *
+ * Fifteen minutes is chosen against the measured session distribution (p50
+ * 14.7 min): a room hears at most one holding line per typical unit of work,
+ * which is the point at which an interim is still a courtesy rather than a nag.
+ *
+ * A plain constant, with no environment in it, so the pure functions below can
+ * fall back to it without reading anything.
+ */
+export const DEFAULT_ROOM_INTERIM_WINDOW_MS = 15 * 60_000;
+
+/**
+ * How long one outcome notice suppresses a byte-identical copy of itself in the
+ * same room. Same default, separately named and separately overridable: the two
+ * are different judgements and collapsing them would mean tuning one retunes
+ * the other by accident.
+ */
+export const DEFAULT_ROOM_NOTICE_WINDOW_MS = 15 * 60_000;
+
+/**
+ * The configured interim window. A FUNCTION, read at the edge — see the header.
+ * @param {object} [env]
+ * @returns {number}
+ */
+export function roomInterimWindowMs(env = process.env) {
+  return num(env && env.ASSURANCE_ROOM_INTERIM_WINDOW_MS, DEFAULT_ROOM_INTERIM_WINDOW_MS);
+}
+
+/**
+ * The configured identical-notice window. Same reasoning as above.
+ * @param {object} [env]
+ * @returns {number}
+ */
+export function roomNoticeWindowMs(env = process.env) {
+  return num(env && env.ASSURANCE_ROOM_NOTICE_WINDOW_MS, DEFAULT_ROOM_NOTICE_WINDOW_MS);
+}
+
+/** Entries older than this are landfill: they can no longer refuse anything. */
+const RETAIN_WINDOWS = 2;
+
+/** The shape on disk. `v` is there so a future migration is not a guess. */
+export function _emptyLedger() {
+  return { v: 1, rooms: {}, notices: {} };
+}
+
+/**
+ * The room's identity: the service and the channel, normalised.
+ *
+ * Deliberately NOT the thread, the sender or the obligation. A thread-scoped
+ * budget would have permitted exactly the flood that was measured — eight
+ * agents, dozens of threads, one very loud channel.
+ *
+ * @param {object} [o] {service, channel}
+ * @returns {string}
+ */
+export function roomKey(o) {
+  const a = o && typeof o === "object" ? o : {};
+  const norm = (v) => String(v == null ? "" : v).trim().toLowerCase() || "unknown";
+  return `${norm(a.service)}|${norm(a.channel)}`;
+}
+
+/**
+ * A stable, dependency-free digest of a message's text.
+ *
+ * FNV-1a over the trimmed, whitespace-collapsed string. It only ever has to
+ * answer "is this the same sentence again", so a 32-bit non-cryptographic hash
+ * is the right size; a collision costs one suppressed notice, against a
+ * baseline of N identical ones.
+ *
+ * @param {unknown} text
+ * @returns {string}
+ */
+export function textDigest(text) {
+  const s = String(text == null ? "" : text).trim().replace(/\s+/g, " ");
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return `${h.toString(36)}.${s.length}`;
+}
+
+/** The identical-notice key: the room, the notice id, and the sentence itself. */
+export function noticeKey(o) {
+  const a = o && typeof o === "object" ? o : {};
+  const notice = String(a.notice == null ? "" : a.notice).trim().toLowerCase() || "notice";
+  return `${roomKey(a)}|${notice}|${textDigest(a.text)}`;
+}
+
+/** One of the ledger's maps, or an empty one — never a throw, never a null deref. */
+function mapOf(ledger, field) {
+  if (!ledger || typeof ledger !== "object") return {};
+  const r = ledger[field];
+  return r && typeof r === "object" && !Array.isArray(r) ? r : {};
+}
+
+const roomsOf = (ledger) => mapOf(ledger, "rooms");
+const noticesOf = (ledger) => mapOf(ledger, "notices");
+
+/** A stamp we are willing to reason from, or null. */
+function stampAt(map, key) {
+  const v = map[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+/**
+ * PURE. Is `now` still inside the window opened at `lastAt`?
+ *
+ * `now - lastAt` and not `Math.abs(...)`: a clock that has stepped BACKWARDS
+ * (NTP correction, a restored snapshot) yields a negative elapsed, which is
+ * less than any window and therefore reads as "inside it". A free message on
+ * every backwards step is how a budget becomes decorative.
+ */
+function insideWindow(now, lastAt, windowMs) {
+  return !Number.isFinite(now) || now - lastAt < windowMs;
+}
+
+/**
+ * PURE. May this room hear an interim right now?
+ *
+ * @param {object} o
+ * @param {object} o.ledger    the ledger as read (any shape; garbage fails open)
+ * @param {string} o.service
+ * @param {string} o.channel
+ * @param {number} o.now
+ * @param {number} [o.windowMs] defaults to DEFAULT_ROOM_INTERIM_WINDOW_MS —
+ *        the constant, never the environment; the edge resolves the configured
+ *        value and passes it in.
+ * @returns {{allowed:boolean, reason:string, room:string, lastAt:number|null}}
+ */
+export function interimAllowed(o = {}) {
+  const room = roomKey(o);
+  const windowMs = Number.isFinite(o.windowMs) ? o.windowMs : DEFAULT_ROOM_INTERIM_WINDOW_MS;
+  const lastAt = stampAt(roomsOf(o.ledger), room);
+  if (lastAt == null) return { allowed: true, reason: "room-budget-free", room, lastAt: null };
+  if (insideWindow(o.now, lastAt, windowMs)) {
+    return { allowed: false, reason: "room-budget-spent", room, lastAt };
+  }
+  return { allowed: true, reason: "room-budget-window-elapsed", room, lastAt };
+}
+
+/**
+ * PURE. Has this EXACT sentence already been said in this room, recently?
+ *
+ * @param {object} o {ledger, service, channel, notice, text, now, windowMs}
+ * @returns {{allowed:boolean, reason:string, room:string, key:string, lastAt:number|null}}
+ */
+export function noticeAllowed(o = {}) {
+  const room = roomKey(o);
+  const key = noticeKey(o);
+  const windowMs = Number.isFinite(o.windowMs) ? o.windowMs : DEFAULT_ROOM_NOTICE_WINDOW_MS;
+  const lastAt = stampAt(noticesOf(o.ledger), key);
+  if (lastAt == null) return { allowed: true, reason: "room-notice-new", room, key, lastAt: null };
+  if (insideWindow(o.now, lastAt, windowMs)) {
+    return { allowed: false, reason: "room-notice-duplicate", room, key, lastAt };
+  }
+  return { allowed: true, reason: "room-notice-window-elapsed", room, key, lastAt };
+}
+
+/**
+ * PURE. The ledger that results from this room having spoken at `now`.
+ * Returns a NEW object; the input is never mutated.
+ */
+export function recordInterim(o = {}) {
+  const rooms = { ...roomsOf(o.ledger), [roomKey(o)]: Number.isFinite(o.now) ? o.now : 0 };
+  return pruneLedger({
+    ledger: { v: 1, rooms, notices: { ...noticesOf(o.ledger) } },
+    now: o.now,
+    windowMs: o.windowMs,
+    noticeWindowMs: o.noticeWindowMs,
+  });
+}
+
+/**
+ * PURE. The ledger that results from this sentence having been said at `now`.
+ * Returns a NEW object; the input is never mutated.
+ */
+export function recordNotice(o = {}) {
+  const notices = { ...noticesOf(o.ledger), [noticeKey(o)]: Number.isFinite(o.now) ? o.now : 0 };
+  return pruneLedger({
+    ledger: { v: 1, rooms: { ...roomsOf(o.ledger) }, notices },
+    now: o.now,
+    windowMs: o.windowMs,
+    noticeWindowMs: o.noticeWindowMs,
+  });
+}
+
+/**
+ * PURE. Drop entries that can no longer refuse anything.
+ *
+ * Two windows of slack rather than one, so a boundary case is never pruned into
+ * a free message.
+ */
+export function pruneLedger(o = {}) {
+  const windowMs = Number.isFinite(o.windowMs) ? o.windowMs : DEFAULT_ROOM_INTERIM_WINDOW_MS;
+  const noticeWindowMs = Number.isFinite(o.noticeWindowMs) ? o.noticeWindowMs : DEFAULT_ROOM_NOTICE_WINDOW_MS;
+  const now = Number.isFinite(o.now) ? o.now : null;
+  const rooms = roomsOf(o.ledger);
+  const notices = noticesOf(o.ledger);
+  if (now == null) return { v: 1, rooms: { ...rooms }, notices: { ...notices } };
+  const sift = (map, win) => {
+    const keep = {};
+    for (const k of Object.keys(map)) {
+      const at = stampAt(map, k);
+      if (at == null) continue; // a corrupt entry refuses nothing; drop it
+      if (now - at < win * RETAIN_WINDOWS) keep[k] = at;
+    }
+    return keep;
+  };
+  return { v: 1, rooms: sift(rooms, windowMs), notices: sift(notices, noticeWindowMs) };
+}
+
+/**
+ * Where the durable ledger lives — beside the obligations it governs, at the
+ * path the design names.
+ *
+ * It is NOT an obligation record, and the ledger's readers must not treat it as
+ * one: `assurance.listObligations` skips this basename by name. A JSON file in
+ * a directory whose reader parses every `*.json` as a debt was, before that
+ * guard, a phantom record with no `key` and no `state` that `pruneObligations`
+ * tried to unlink once a minute.
+ */
+export function ledgerPath(agentRoot) {
+  return join(String(agentRoot || "."), "state", "obligations", "room-budget.json");
+}
+
+/** The basename the obligation reader must skip. Exported so it is one string. */
+export const LEDGER_BASENAME = "room-budget.json";
+
+/**
+ * Read the durable ledger. Absent or corrupt reads as empty, flagged.
+ * @returns {{v:number, rooms:object, notices:object, degraded?:boolean}}
+ */
+export function readLedger(o = {}) {
+  const impl = o.deps && o.deps.readImpl;
+  if (typeof impl === "function") {
+    try {
+      const led = impl(ledgerPath(o.agentRoot));
+      return led && typeof led === "object" ? led : _emptyLedger();
+    } catch { return { ..._emptyLedger(), degraded: true }; } // an injected reader that throws is still "nothing known"
+  }
+  let raw;
+  try { raw = readFileSync(ledgerPath(o.agentRoot), "utf-8"); }
+  catch { return _emptyLedger(); } // absent is the normal first-run case, not a fault
+  try {
+    const led = JSON.parse(raw);
+    return led && typeof led === "object" ? led : { ..._emptyLedger(), degraded: true };
+  } catch {
+    // A torn or hand-edited file. Fail OPEN and SAY SO — see the module header.
+    return { ..._emptyLedger(), degraded: true };
+  }
+}
+
+/** Persist, reporting a write failure rather than swallowing it. */
+function persist(o, next, room) {
+  const write = (o.deps && o.deps.writeImpl) || writeJsonAtomic;
+  try { write(ledgerPath(o.agentRoot), next); return true; }
+  catch (err) {
+    // The message still goes out — see the fail-open note in the header — but a
+    // spend that did not persist is a budget that is not being kept, so it is
+    // reported rather than swallowed.
+    console.warn(`[room-budget] could not persist spend for ${room}: ${err.message}`);
+    return false;
+  }
+}
+
+/**
+ * THE DURABLE EDGE for interims. Decide, and if the answer is yes, spend.
+ *
+ * Read-decide-write is not atomic. Two callers can therefore both claim one
+ * window, and there are two distinct ways for that to happen:
+ *
+ *   ACROSS PROCESSES — two daemons sharing one AGENT_DIR, which is what an
+ *   operator has while debugging beside the launchd job. Same exposure the
+ *   obligation ledger already carries; the sweep's `foreignOwnerAlive` guard
+ *   covers it from the other side.
+ *
+ *   WITHIN ONE PROCESS — two overlapping sweeps on the 60-second health timer.
+ *   This one is likelier, because branch (e) peeks with `commit:false`, then
+ *   awaits a model call, and only commits after a successful send: a daemon
+ *   holding enough eligible obligations spends more than a tick in generation
+ *   alone. It is closed at the other end — `sweepObligations` refuses to run
+ *   re-entrantly — rather than with a lock here, because a lock in this
+ *   function would serialise every caller in the fleet to fix one caller's
+ *   overlap, and a stuck lock file would gag a room permanently.
+ *
+ * Either way the failure mode is one extra message against a baseline of up to
+ * N per room.
+ *
+ * @param {object} o
+ * @param {string} o.service
+ * @param {string} o.channel
+ * @param {number} o.now            INJECTED clock; omitting it is a caller bug
+ * @param {string} o.agentRoot
+ * @param {number} [o.windowMs]     defaults to the CONFIGURED window
+ * @param {boolean} [o.commit=true] false asks the question WITHOUT spending the
+ *        budget. The caller needs this because the message it wants to send may
+ *        not exist yet: the interim's text comes from a model call that can
+ *        fail, and a budget spent on a message that was never composed gags the
+ *        room for fifteen minutes in exchange for nothing.
+ * @param {object} [o.deps] {readImpl, writeImpl}
+ * @returns {{allowed:boolean, reason:string, room:string, lastAt:number|null, degraded?:boolean, committed?:boolean}}
+ */
+export function claimRoomInterim(o = {}) {
+  const room = roomKey(o);
+  if (!Number.isFinite(o.now)) {
+    // No clock, no decision. Refusing is right here and only here: the caller
+    // has a defect, and a defective caller must not be handed a budget it
+    // cannot account for.
+    return { allowed: false, reason: "no-clock", room, lastAt: null };
+  }
+  const windowMs = Number.isFinite(o.windowMs) ? o.windowMs : roomInterimWindowMs();
+  const ledger = readLedger(o);
+  const degraded = ledger.degraded === true;
+  const verdict = interimAllowed({ ledger, service: o.service, channel: o.channel, now: o.now, windowMs });
+  if (!verdict.allowed) return degraded ? { ...verdict, degraded } : verdict;
+  if (o.commit === false) return degraded ? { ...verdict, degraded, committed: false } : { ...verdict, committed: false };
+
+  const next = recordInterim({ ledger, service: o.service, channel: o.channel, now: o.now, windowMs });
+  const ok = persist(o, next, room);
+  if (!ok) return { ...verdict, degraded: true, committed: true };
+  return degraded ? { ...verdict, degraded, committed: true } : { ...verdict, committed: true };
+}
+
+/**
+ * THE DURABLE EDGE for outcome notices: may this EXACT sentence be said here
+ * again?
+ *
+ * WHY THIS EXISTS, given that outcome notices are deliberately ungoverned by
+ * the interim budget. The per-obligation dedupe (`assurance.noticeAlreadySaid`)
+ * is keyed on the obligation RECORD, so it suppresses the repeat that R4
+ * produced — notice, retry, a fresh record under the same key, notice again.
+ * It cannot suppress SIBLINGS: twenty separate asks in one room whose sessions
+ * all die the same way are twenty separate records, and each composes the same
+ * fixed sentence, because `composeFailure`'s stale text has no per-ask content
+ * in it at all. Measured shape, and the one the live sample showed: the same
+ * failure sentence three times in one minute.
+ *
+ * The test applied here is therefore NOT "has this room had enough". It is
+ * "would this add anything": a sentence byte-identical to one already on screen
+ * cannot tell the reader which ask it is about, so the second copy is volume
+ * without information. A notice that differs — a different cause, a different
+ * excerpt, "retrying" versus "I have stopped" — is NOT suppressed, at any
+ * volume, because it carries a fact the reader does not have.
+ *
+ * The escalation record is written per obligation regardless, so nothing is
+ * lost operationally: an operator still sees every dead ask in needs-attention.
+ *
+ * @param {object} o
+ * @param {string} o.service
+ * @param {string} o.channel
+ * @param {string} o.notice    the notice id (see assurance.NOTICE)
+ * @param {string} o.text      the exact composed sentence
+ * @param {number} o.now       INJECTED clock
+ * @param {string} o.agentRoot
+ * @param {number} [o.windowMs]
+ * @param {boolean} [o.commit=true]
+ * @param {object} [o.deps] {readImpl, writeImpl}
+ * @returns {{allowed:boolean, reason:string, room:string, key:string, lastAt:number|null, degraded?:boolean, committed?:boolean}}
+ */
+export function claimRoomNotice(o = {}) {
+  const room = roomKey(o);
+  const key = noticeKey(o);
+  if (!Number.isFinite(o.now)) {
+    // FAIL OPEN, and the OPPOSITE way to claimRoomInterim. A missing clock must
+    // not be able to swallow "your work died": the interim is a courtesy that
+    // is safe to drop, and this is not.
+    return { allowed: true, reason: "no-clock-fail-open", room, key, lastAt: null, degraded: true };
+  }
+  const windowMs = Number.isFinite(o.windowMs) ? o.windowMs : roomNoticeWindowMs();
+  const ledger = readLedger(o);
+  const degraded = ledger.degraded === true;
+  const verdict = noticeAllowed({
+    ledger, service: o.service, channel: o.channel, notice: o.notice, text: o.text, now: o.now, windowMs,
+  });
+  if (!verdict.allowed) return degraded ? { ...verdict, degraded } : verdict;
+  if (o.commit === false) return degraded ? { ...verdict, degraded, committed: false } : { ...verdict, committed: false };
+
+  const next = recordNotice({
+    ledger, service: o.service, channel: o.channel, notice: o.notice, text: o.text, now: o.now, noticeWindowMs: windowMs,
+  });
+  const ok = persist(o, next, room);
+  if (!ok) return { ...verdict, degraded: true, committed: true };
+  return degraded ? { ...verdict, degraded, committed: true } : { ...verdict, committed: true };
+}
+
+export default {
+  DEFAULT_ROOM_INTERIM_WINDOW_MS,
+  DEFAULT_ROOM_NOTICE_WINDOW_MS,
+  roomInterimWindowMs,
+  roomNoticeWindowMs,
+  roomKey,
+  noticeKey,
+  textDigest,
+  interimAllowed,
+  noticeAllowed,
+  recordInterim,
+  recordNotice,
+  pruneLedger,
+  ledgerPath,
+  LEDGER_BASENAME,
+  readLedger,
+  claimRoomInterim,
+  claimRoomNotice,
+};