@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/budget-guard.envelope.test.mjs

@@ -1,476 +0,0 @@
-/**
- * budget-guard.envelope.test.mjs — THE CEILING IS REAL.
- *
- * The other budget-guard suite covers banding arithmetic against an injected
- * cap. This one covers the thing that was actually missing: where the ceiling
- * COMES FROM (hq's `seatBudgetCents`, via the mandate cache), how it is prorated
- * and reconciled month-to-date, what happens when the local config disagrees
- * with it, and what an unfunded seat is told.
- *
- * Hermetic: every test builds its own agent root with a hand-written mandate
- * cache + ledger and injects a fixed clock.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { promises as fsp } from "node:fs";
-import { writeFileSync, mkdirSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import {
-  dailyStatus,
-  dailyAllowance,
-  readSeatEnvelope,
-  monthToDate,
-  postureForBand,
-  MODES,
-} from "./budget-guard.mjs";
-
-// 2026-06-15T12:00Z — mid-month on purpose: 30-day June, day 15, 16 days left.
-const FIXED = Date.UTC(2026, 5, 15, 12, 0, 0);
-const DATE = "2026-06-15";
-const clk = () => FIXED;
-
-async function makeAgentRoot() {
-  const dir = join(tmpdir(), `bg-envelope-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
-  mkdirSync(join(dir, "state", "cost-tracking"), { recursive: true });
-  mkdirSync(join(dir, "state", "mandate"), { recursive: true });
-  return dir;
-}
-async function rm(dir) { try { await fsp.rm(dir, { recursive: true, force: true }); } catch { /* */ } }
-
-/** A measured ledger row — the shape a correctly-instrumented caller writes. */
-function row(usd, date = DATE) {
-  return JSON.stringify({
-    ts: `${date}T10:00:00.000Z`,
-    total_cost_usd: usd,
-    estimated_usd: usd / 3, // deliberately WRONG, and deliberately ignored
-    model: "opus",
-    cadence: "inbox",
-    source: "dispatcher",
-    input_tokens: 1275,
-    output_tokens: 9152,
-    cache_read_input_tokens: 1458891,
-  });
-}
-
-function seedLedger(root, usdList, date = DATE) {
-  writeFileSync(join(root, "state", "cost-tracking", `${date}.jsonl`), usdList.map((u) => row(u, date)).join("\n") + "\n");
-}
-
-/** A mandate cache exactly as `mandate.get` → `writeCache` leaves it. */
-function seedMandate(root, { seatBudgetCents, supervisor = "M-SUPERVISOR", source = "server" } = {}) {
-  writeFileSync(
-    join(root, "state", "mandate", "cache.json"),
-    JSON.stringify({
-      version: 7,
-      checksum: "deadbeef",
-      source,
-      fetchedAt: `${DATE}T08:00:00.000Z`,
-      body: {
-        contractVersion: 1,
-        memberId: "A016",
-        objectives: [],
-        proposed: [],
-        budgetCentsPerPeriod: null,
-        seatBudgetCents,
-        budgetPeriod: seatBudgetCents == null ? null : "monthly",
-        budgetSource: "employee.payBasis.meteredBudget",
-        collaborators: supervisor ? [{ memberId: supervisor, role: "REVIEWER", source: "workforceMember.supervisorId" }] : [],
-        reactsTo: [],
-        degradations: seatBudgetCents == null
-          ? [{ field: "seatBudgetCents", reason: "no Employee row is linked to this member" }]
-          : [],
-        generatedAt: `${DATE}T07:00:00.000Z`,
-      },
-    }, null, 2)
-  );
-}
-
-// ---------------------------------------------------------------------------
-// where the envelope comes from
-// ---------------------------------------------------------------------------
-
-test("the envelope is read off the mandate cache hq published", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 90_000 }); // $900/month
-    const env = readSeatEnvelope({ agentRoot: root, now: clk });
-    assert.equal(env.seatBudgetCents, 90_000);
-    assert.equal(env.budgetPeriod, "monthly");
-    assert.equal(env.supervisorMemberId, "M-SUPERVISOR");
-    assert.equal(env.source, "employee.payBasis.meteredBudget");
-    assert.equal(env.reason, null);
-  } finally { await rm(root); }
-});
-
-test("an unfunded seat says WHY, in hq's own words, and is never assigned a number", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: null });
-    const env = readSeatEnvelope({ agentRoot: root, now: clk });
-    assert.equal(env.seatBudgetCents, null);
-    assert.match(env.reason, /no Employee row is linked to this member/);
-
-    const st = dailyStatus({ agentRoot: root, now: clk, capUSD: 25 });
-    assert.equal(st.funded, false);
-    assert.equal(st.capSource, "local-config");
-    assert.ok(
-      st.degradations.some((d) => /UNFUNDED SEAT/.test(d) && /NOT being enforced/.test(d)),
-      "an agent that cannot know its funding must SAY so, on the wire and in the log"
-    );
-  } finally { await rm(root); }
-});
-
-test("a LOCAL (never-adopted) mandate cache is not mistaken for a funded envelope", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: null, source: "local" });
-    const env = readSeatEnvelope({ agentRoot: root, now: clk });
-    assert.equal(env.seatBudgetCents, null);
-    assert.match(env.reason, /no Employee row|LOCAL/);
-  } finally { await rm(root); }
-});
-
-// ---------------------------------------------------------------------------
-// proration + month-to-date reconciliation
-// ---------------------------------------------------------------------------
-
-test("today's allowance is the REMAINING envelope over the REMAINING days", async () => {
-  const root = await makeAgentRoot();
-  try {
-    // $960/month, June (30 days), on the 15th → 16 days left, nothing spent yet.
-    seedMandate(root, { seatBudgetCents: 96_000 });
-    const a = dailyAllowance({ agentRoot: root, now: clk, capUSD: 10_000 });
-    assert.equal(a.funded, true);
-    assert.equal(a.capSource, "seat-envelope");
-    assert.equal(a.envelope.remainingDays, 16);
-    assert.equal(a.allowanceUSD, 60); // 960 / 16
-  } finally { await rm(root); }
-});
-
-test("a quiet week funds a busy one: unspent envelope raises today's allowance", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 96_000 }); // $960
-    // Days 1-14 were quiet: $60 total against a flat-rate expectation of ~$448.
-    seedLedger(root, [60], "2026-06-03");
-    const a = dailyAllowance({ agentRoot: root, now: clk, capUSD: 10_000 });
-    assert.equal(a.month.spentUSD, 60);
-    assert.equal(a.allowanceUSD, +((960 - 60) / 16).toFixed(6), "the underspend rolls forward, it does not expire");
-    assert.ok(a.allowanceUSD > 960 / 30, "and it is strictly more than a flat 1/30 slice");
-  } finally { await rm(root); }
-});
-
-test("a blown month binds today even when today itself is quiet", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 10_000 }); // $100/month
-    seedLedger(root, [130], "2026-06-04");         // 130% of the month, already
-    seedLedger(root, [0.5]);                        // today: almost nothing
-    const st = dailyStatus({ agentRoot: root, now: clk, capUSD: 10_000 });
-    assert.equal(st.monthPct, 130.5);
-    assert.equal(st.band, 125, "the month-to-date reading is the binding one");
-    assert.equal(st.mode, MODES.SUSPENDED);
-  } finally { await rm(root); }
-});
-
-test("monthToDate sums only this month's date-stamped files", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedLedger(root, [10], "2026-06-01");
-    seedLedger(root, [5], "2026-06-14");
-    seedLedger(root, [1000], "2026-05-30"); // last month — must not count
-    const m = monthToDate({ agentRoot: root, now: clk });
-    assert.equal(m.spentUSD, 15);
-    assert.equal(m.days, 2);
-  } finally { await rm(root); }
-});
-
-// ---------------------------------------------------------------------------
-// the two ceilings disagreeing
-// ---------------------------------------------------------------------------
-
-test("when the envelope and the local cap disagree, the LOWER binds and it is logged", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 96_000 }); // $60/day allowance
-    const a = dailyAllowance({ agentRoot: root, now: clk, capUSD: 25 });
-    assert.equal(a.allowanceUSD, 25);
-    assert.equal(a.capSource, "local-config");
-    assert.ok(a.degradations.some((d) => /the LOWER binds/.test(d)), "a disagreement is never silent");
-  } finally { await rm(root); }
-});
-
-test("a local cap CANNOT authorise more than the org funded", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 1_600 }); // $16/month → $1/day
-    const a = dailyAllowance({ agentRoot: root, now: clk, capUSD: 500 });
-    assert.equal(a.allowanceUSD, 1, "the seat's own config may tighten the ceiling, never raise it");
-    assert.equal(a.capSource, "seat-envelope");
-  } finally { await rm(root); }
-});
-
-// ---------------------------------------------------------------------------
-// the ladder itself
-// ---------------------------------------------------------------------------
-
-test("postureForBand is the ladder, written down once", () => {
-  const at = (b) => postureForBand(b);
-
-  assert.equal(at(0).mode, MODES.NORMAL);
-  assert.equal(at(0).escalateToSupervisor, false);
-  assert.equal(at(0).selfDirected, true);
-
-  // 80 — a notice, and nothing else. This is the rung that must NOT degrade.
-  assert.equal(at(80).mode, MODES.NORMAL);
-  assert.equal(at(80).escalateToSupervisor, true);
-  assert.equal(at(80).cheapModelOnly, false);
-  assert.equal(at(80).selfDirected, true);
-
-  // 100 — degrade the rung.
-  assert.equal(at(100).mode, MODES.DEGRADED);
-  assert.equal(at(100).cheapModelOnly, true);
-  assert.equal(at(100).maxFanout, 1);
-  assert.equal(at(100).maxRung, 4, "rung 5 is `team` (sub-agent fan-out) — capped out");
-  assert.equal(at(100).selfDirected, false);
-  assert.equal(at(100).suspendOutcomeObligations, false);
-
-  // 125 — suspend the obligations, not the seat.
-  assert.equal(at(125).mode, MODES.SUSPENDED);
-  assert.equal(at(125).suspendOutcomeObligations, true);
-  assert.equal(at(125).refuseNonHumanSpawn, false);
-
-  // 150 — refuse, at spawn level only.
-  assert.equal(at(150).mode, MODES.REFUSED);
-  assert.equal(at(150).refuseNonHumanSpawn, true);
-});
-
-test("end to end: a funded seat that overspends lands in the right posture", async () => {
-  const root = await makeAgentRoot();
-  try {
-    // $480/month → $30/day allowance on the 15th (16 days left).
-    seedMandate(root, { seatBudgetCents: 48_000 });
-    const cases = [
-      [15, 0, MODES.NORMAL],
-      [25, 80, MODES.NORMAL],
-      [31, 100, MODES.DEGRADED],
-      [38, 125, MODES.SUSPENDED],
-      [46, 150, MODES.REFUSED],
-    ];
-    for (const [usd, band, mode] of cases) {
-      seedLedger(root, [usd]);
-      const st = dailyStatus({ agentRoot: root, now: clk, capUSD: 10_000 });
-      assert.equal(st.capUSD, 30, "the ceiling is the seat envelope, prorated");
-      assert.equal(st.band, band, `$${usd}/$30 should be band ${band}, got ${st.band} (${st.pct}%)`);
-      assert.equal(st.mode, mode);
-      assert.equal(st.supervisorMemberId, "M-SUPERVISOR");
-    }
-  } finally { await rm(root); }
-});
-
-test("the authoritative cost column is what binds — not the estimate that ran 2.6x low", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 48_000 }); // $30/day
-    // Each row bills $12 authoritative / $4 estimated. Three rows = $36 real.
-    seedLedger(root, [12, 12, 12]);
-    const st = dailyStatus({ agentRoot: root, now: clk, capUSD: 10_000 });
-    assert.equal(st.spentUSD, 36, "total_cost_usd, not estimated_usd");
-    assert.equal(st.pct, 120);
-    assert.equal(st.band, 100);
-    assert.equal(st.mode, MODES.DEGRADED);
-    // On the old estimated_usd basis this day read $12 of $30 = band 0.
-    assert.ok(st.pct > 100, "the same day was invisible to the governor before");
-  } finally { await rm(root); }
-});
-
-test("a governance band never depends on the seat's own writable config alone", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 3_000 }); // $30/month → $1.875/day
-    seedLedger(root, [5]);
-    // The seat "raises" its own local cap to $1000/day. It changes nothing.
-    const st = dailyStatus({ agentRoot: root, now: clk, capUSD: 1000 });
-    assert.equal(st.capSource, "seat-envelope");
-    assert.equal(st.mode, MODES.REFUSED);
-  } finally { await rm(root); }
-});
-
-// ---------------------------------------------------------------------------
-// THE LATCH — the configuration where the invariant above used to be FALSE
-// ---------------------------------------------------------------------------
-
-test("a seat cannot walk itself OUT of a band by raising its own local cap", async () => {
-  const root = await makeAgentRoot();
-  try {
-    // The ORDINARY posture, and the one the invariant test above never covers:
-    // a well-funded seat ($480/month → $30.00/day on day 15 of 30) whose BINDING
-    // cap is the smaller local `config/recovery.yaml` number. The test above uses
-    // a $30/MONTH envelope, where the envelope share ($1.875/day) is so far below
-    // spend that raising the local cap provably cannot help — so it certifies the
-    // invariant on the one fixture where it cannot fail.
-    seedMandate(root, { seatBudgetCents: 48_000 });
-    seedLedger(root, [28]);
-
-    const before = dailyStatus({ agentRoot: root, now: clk, capUSD: 25 });
-    assert.equal(before.capSource, "local-config");
-    assert.equal(before.band, 100, "$28 against a $25 binding cap is 112%");
-    assert.equal(before.mode, MODES.DEGRADED);
-
-    // One edit to a file inside the seat's own repo, raising the local cap above
-    // the envelope share. Without the latch this read band 80 / mode "normal".
-    const after = dailyStatus({ agentRoot: root, now: clk, capUSD: 1000 });
-    assert.equal(after.bandingCapUSD, 25, "banding stays on the lowest cap this period ran under");
-    assert.equal(after.band, 100, "the seat is still degraded");
-    assert.equal(after.mode, MODES.DEGRADED);
-    assert.ok(
-      after.degradations.some((d) => /cannot raise its own ceiling/.test(d)),
-      "and it SAYS the raise was ignored — fail-open is fine, silent is not"
-    );
-  } finally { await rm(root); }
-});
-
-test("hq RAISING the envelope does take effect immediately — the latch is not a ratchet", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 48_000 });
-    seedLedger(root, [28]);
-    assert.equal(dailyStatus({ agentRoot: root, now: clk, capUSD: 25 }).band, 100);
-
-    // hq funds the seat properly. That is an act the seat cannot perform, so the
-    // latch resets on it (in BOTH directions — a governance change is a fact).
-    seedMandate(root, { seatBudgetCents: 480_000 });
-    const after = dailyStatus({ agentRoot: root, now: clk, capUSD: 1000 });
-    assert.equal(after.band, 0);
-    assert.equal(after.mode, MODES.NORMAL);
-  } finally { await rm(root); }
-});
-
-// ---------------------------------------------------------------------------
-// the envelope's own provenance and freshness
-// ---------------------------------------------------------------------------
-
-test("a LOCALLY-derived mandate body is never accepted as the org-funded ceiling", async () => {
-  const root = await makeAgentRoot();
-  try {
-    // `lib/setup/sections/mandate.mjs` writes a local body when hq is
-    // unreachable. A seatBudgetCents on such a record is the seat setting its own
-    // ceiling — the one thing this module exists to prevent. Provenance was
-    // checked only on the MISS path, so a local body carrying a number was
-    // enforced as if hq had published it.
-    seedMandate(root, { seatBudgetCents: 90_000, source: "local" });
-    const env = readSeatEnvelope({ agentRoot: root, now: clk });
-    assert.equal(env.seatBudgetCents, null);
-    assert.match(env.reason, /source is "local".*may not be used as the org-funded ceiling/s);
-    assert.equal(dailyAllowance({ agentRoot: root, now: clk, capUSD: 25 }).funded, false);
-  } finally { await rm(root); }
-});
-
-test("an EXPIRED envelope stops being authoritative — hq can revoke funding while we are partitioned", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 90_000 });
-    // 8 days after the cache was fetched. `fetchedAt` was not read at all, so a
-    // revoked seat kept producing funded:true and a live allowance forever, with
-    // "employee.payBasis.meteredBudget" asserted as provenance rather than
-    // verified.
-    const later = () => FIXED + 8 * 86_400_000;
-    const env = readSeatEnvelope({ agentRoot: root, now: later });
-    assert.equal(env.seatBudgetCents, null);
-    assert.match(env.reason, /no longer authoritative/);
-
-    const a = dailyAllowance({ agentRoot: root, now: later, capUSD: 25 });
-    assert.equal(a.funded, false);
-    assert.equal(a.capSource, "local-config");
-    assert.ok(a.degradations.some((d) => /UNFUNDED SEAT/.test(d)));
-  } finally { await rm(root); }
-});
-
-test("an AGING envelope is still enforced, and says so", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 90_000 });
-    const later = () => FIXED + 2 * 86_400_000;
-    const env = readSeatEnvelope({ agentRoot: root, now: later });
-    assert.equal(env.seatBudgetCents, 90_000, "an unrefreshed envelope is still hq's number");
-    assert.match(env.staleReason, /last fetched from hq/);
-  } finally { await rm(root); }
-});
-
-// ---------------------------------------------------------------------------
-// blind ⇒ degrade
-// ---------------------------------------------------------------------------
-
-test("a day nobody could measure is DEGRADED, not trusted — and no price is invented", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 480_000 });
-    // Three sessions ran; not one could be measured or priced, and there is no
-    // measured row anywhere in the month to impute from. The old code imputed a
-    // hard-coded $0.25/session, reported band 0, and `blind` — which it computed
-    // and surfaced — was enforced by nobody.
-    writeFileSync(
-      join(root, "state", "cost-tracking", `${DATE}.jsonl`),
-      Array.from({ length: 3 }, () => JSON.stringify({
-        ts: `${DATE}T10:00:00.000Z`, model: "opus", source: "dispatcher",
-        measurement: "unknown", unmeasured_reason: "json-parse-failed",
-        input_tokens: null, output_tokens: null, estimated_usd: null, total_cost_usd: null,
-      })).join("\n") + "\n"
-    );
-
-    const st = dailyStatus({ agentRoot: root, now: clk, capUSD: 1000 });
-    assert.equal(st.spentUSD, 0, "we do not invent a number we have no evidence for");
-    assert.equal(st.blind, true);
-    assert.equal(st.band, 100, "we cannot measure, therefore we degrade");
-    assert.equal(st.mode, MODES.DEGRADED);
-    assert.equal(st.posture.selfDirected, false);
-    assert.ok(st.degradations.some((d) => /NONE could be/.test(d)));
-  } finally { await rm(root); }
-});
-
-test("a day with SOME measured rows imputes from evidence instead of degrading", async () => {
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 480_000 });
-    const rows = [
-      row(2), row(2),
-      JSON.stringify({ ts: `${DATE}T11:00:00.000Z`, model: "opus", source: "dispatcher", measurement: "unknown", input_tokens: null, output_tokens: null, estimated_usd: null, total_cost_usd: null }),
-    ];
-    writeFileSync(join(root, "state", "cost-tracking", `${DATE}.jsonl`), rows.join("\n") + "\n");
-    const st = dailyStatus({ agentRoot: root, now: clk, capUSD: 1000 });
-    assert.equal(st.spentUSD, 6, "$2 + $2 measured, + $2 imputed at the day's own mean");
-    assert.equal(st.blind, false);
-    assert.equal(st.band, 0);
-  } finally { await rm(root); }
-});
-
-test("the cap latch SURVIVES a budget notice being written to the same period file", async () => {
-  // The notice ledger and the cap latch share one UTC-date-stamped file, and
-  // `maybeNotify` merge-writes over whatever `readNotified` hands back. If that
-  // read drops the latch fields, the first notice of the period silently resets
-  // the latch — and the latch is the only thing stopping a seat from demoting
-  // its own band by editing its own config.
-  const { maybeNotify } = await import("./budget-guard.mjs");
-  const { readFileSync } = await import("node:fs");
-  const root = await makeAgentRoot();
-  try {
-    seedMandate(root, { seatBudgetCents: 48_000 });
-    seedLedger(root, [28]);
-
-    // Establish the latch at $25 (band 100), then fire the notice.
-    assert.equal(dailyStatus({ agentRoot: root, now: clk, capUSD: 25 }).bandingCapUSD, 25);
-    const n = maybeNotify({ agentRoot: root, now: clk, capUSD: 25, log: () => {} });
-    assert.equal(n.notified, true);
-
-    const onDisk = JSON.parse(
-      readFileSync(join(root, "state", "cost-tracking", `${DATE}.budget.json`), "utf-8")
-    );
-    assert.equal(onDisk.min_binding_cap_usd, 25, "the latch is still on disk after the notice write");
-
-    // And the seat still cannot raise its way out of the band.
-    assert.equal(dailyStatus({ agentRoot: root, now: clk, capUSD: 1000 }).band, 100);
-  } finally { await rm(root); }
-});