@cohortapp/agent-sdk 2.17.0 → 2.18.5

package/lib/diagnostics/alerts.test.mjs

@@ -1,318 +0,0 @@
-/**
- * alerts.test.mjs — coverage for lib/diagnostics/alerts.mjs.
- *
- * Each behavioral rule must FIRE at/above its threshold and stay QUIET below it,
- * emitAlerts must post every alert to an injected sink (no live call), and both
- * entry points must never throw on garbage input.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  evaluateAlerts,
-  emitAlerts,
-  loadThresholds,
-  mergeThresholds,
-  DEFAULT_THRESHOLDS,
-  _internals,
-} from "./alerts.mjs";
-
-const ids = (alerts) => alerts.map((a) => a.id).sort();
-const byId = (alerts, id) => alerts.find((a) => a.id === id);
-
-// ---------------------------------------------------------------------------
-// refusal spike
-// ---------------------------------------------------------------------------
-
-test("refusal_spike: quiet below warn, warns at warn, critical at crit", () => {
-  // Defaults: warn 10, crit 25, across counters refusal/policy.refusal/classifier.refusal.
-  assert.equal(byId(evaluateAlerts({ snapshot: { refusal: 9 } }), "refusal_spike"), undefined);
-
-  const warn = byId(evaluateAlerts({ snapshot: { refusal: 10 } }), "refusal_spike");
-  assert.ok(warn, "fires at warn threshold");
-  assert.equal(warn.severity, "warning");
-
-  // Summed across the configured counters.
-  const summed = byId(
-    evaluateAlerts({ snapshot: { refusal: 12, "policy.refusal": 8, "classifier.refusal": 6 } }),
-    "refusal_spike"
-  );
-  assert.ok(summed);
-  assert.equal(summed.severity, "critical"); // 26 >= 25
-  assert.match(summed.detail, /26 refusals/);
-});
-
-// ---------------------------------------------------------------------------
-// guard fail-open spike (named + suffix match)
-// ---------------------------------------------------------------------------
-
-test("guard_fail_spike: suffix-matched counters are summed and banded", () => {
-  // Below warn (5).
-  assert.equal(
-    byId(evaluateAlerts({ snapshot: { "rate_guard.fail_open": 4 } }), "guard_fail_spike"),
-    undefined
-  );
-
-  // At warn: 5 across suffix matches.
-  const warn = byId(
-    evaluateAlerts({ snapshot: { "rate_guard.fail_open": 3, "budget_guard.persist_failed": 2 } }),
-    "guard_fail_spike"
-  );
-  assert.ok(warn);
-  assert.equal(warn.severity, "warning");
-
-  // At crit: 20.
-  const crit = byId(
-    evaluateAlerts({ snapshot: { "x.fail_open": 10, "y.degraded": 10 } }),
-    "guard_fail_spike"
-  );
-  assert.ok(crit);
-  assert.equal(crit.severity, "critical");
-
-  // A non-matching counter must NOT contribute.
-  assert.equal(
-    byId(evaluateAlerts({ snapshot: { "some.unrelated_counter": 99 } }), "guard_fail_spike"),
-    undefined
-  );
-});
-
-// ---------------------------------------------------------------------------
-// cost per session p99
-// ---------------------------------------------------------------------------
-
-test("cost_per_session_p99: uses p99 of the distribution when present", () => {
-  // 10 cheap sessions, one $4 outlier — p99 (nearest-rank) picks the outlier.
-  const perSessionUSD = [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 4.0];
-  const a = byId(
-    evaluateAlerts({ ledger: { sessions: 10, spentUSD: 4.9, perSessionUSD } }),
-    "cost_per_session_p99"
-  );
-  assert.ok(a, "fires when p99 exceeds crit");
-  assert.equal(a.severity, "critical"); // 4.0 >= crit 3.0
-  assert.match(a.detail, /p99/);
-});
-
-test("cost_per_session_p99: falls back to mean when no distribution", () => {
-  // mean = 10/5 = 2.0 → warning (>=1.5, <3.0).
-  const a = byId(
-    evaluateAlerts({ ledger: { sessions: 5, spentUSD: 10 } }),
-    "cost_per_session_p99"
-  );
-  assert.ok(a);
-  assert.equal(a.severity, "warning");
-  assert.match(a.detail, /mean/);
-});
-
-test("cost_per_session_p99: stays quiet below the warn threshold", () => {
-  // mean = 5/5 = 1.0 < warn 1.5.
-  assert.equal(
-    byId(evaluateAlerts({ ledger: { sessions: 5, spentUSD: 5 } }), "cost_per_session_p99"),
-    undefined
-  );
-});
-
-test("cost_per_session_p99: does not fire on a tiny sample (minSessions)", () => {
-  // Only 4 sessions (< minSessions 5) even though per-session spend is huge.
-  assert.equal(
-    byId(evaluateAlerts({ ledger: { sessions: 4, spentUSD: 40 } }), "cost_per_session_p99"),
-    undefined
-  );
-});
-
-// ---------------------------------------------------------------------------
-// absent agent
-// ---------------------------------------------------------------------------
-
-test("absent_agent: quiet below warn, warns then crits on heartbeat age", () => {
-  // Defaults: warn 600s, crit 1800s.
-  assert.equal(
-    byId(evaluateAlerts({ presence: { heartbeatAgeSec: 300 } }), "absent_agent"),
-    undefined
-  );
-
-  const warn = byId(evaluateAlerts({ presence: { heartbeatAgeSec: 600 } }), "absent_agent");
-  assert.ok(warn);
-  assert.equal(warn.severity, "warning");
-
-  const crit = byId(evaluateAlerts({ presence: { heartbeatAgeSec: 2000 } }), "absent_agent");
-  assert.ok(crit);
-  assert.equal(crit.severity, "critical");
-
-  // No heartbeat age supplied → absent_agent does NOT fire (daemon_down covers it).
-  assert.equal(byId(evaluateAlerts({ presence: {} }), "absent_agent"), undefined);
-});
-
-// ---------------------------------------------------------------------------
-// daemon down
-// ---------------------------------------------------------------------------
-
-test("daemon_down: explicit flag is critical; stale heartbeat is banded", () => {
-  const flagged = byId(evaluateAlerts({ presence: { daemonDown: true } }), "daemon_down");
-  assert.ok(flagged);
-  assert.equal(flagged.severity, "critical");
-
-  // Defaults: warn 120s, crit 300s.
-  assert.equal(
-    byId(evaluateAlerts({ presence: { daemonHealthAgeSec: 60 } }), "daemon_down"),
-    undefined
-  );
-  const warn = byId(evaluateAlerts({ presence: { daemonHealthAgeSec: 150 } }), "daemon_down");
-  assert.ok(warn);
-  assert.equal(warn.severity, "warning");
-  const crit = byId(evaluateAlerts({ presence: { daemonHealthAgeSec: 600 } }), "daemon_down");
-  assert.ok(crit);
-  assert.equal(crit.severity, "critical");
-});
-
-// ---------------------------------------------------------------------------
-// determinism, ordering, custom thresholds
-// ---------------------------------------------------------------------------
-
-test("evaluateAlerts: deterministic, critical-first ordering", () => {
-  const args = {
-    snapshot: { refusal: 30 }, // critical refusal_spike
-    presence: { heartbeatAgeSec: 700 }, // warning absent_agent
-  };
-  const a = evaluateAlerts(args);
-  assert.deepEqual(ids(a), ["absent_agent", "refusal_spike"]);
-  // Critical sorts before warning.
-  assert.equal(a[0].severity, "critical");
-  assert.equal(a[0].id, "refusal_spike");
-  // Repeated evaluation is identical.
-  assert.deepEqual(evaluateAlerts(args), a);
-});
-
-test("evaluateAlerts: custom thresholds override defaults", () => {
-  // Lower the refusal warn to 2 so 3 refusals fires.
-  const a = byId(
-    evaluateAlerts({ snapshot: { refusal: 3 }, thresholds: { refusalSpike: { warnCount: 2, critCount: 100 } } }),
-    "refusal_spike"
-  );
-  assert.ok(a);
-  assert.equal(a.severity, "warning");
-});
-
-test("evaluateAlerts: clean inputs produce no alerts", () => {
-  const a = evaluateAlerts({
-    snapshot: { some_ok_counter: 3 },
-    ledger: { sessions: 100, spentUSD: 10 }, // mean 0.1 — fine
-    presence: { heartbeatAgeSec: 5, daemonHealthAgeSec: 5 },
-  });
-  assert.deepEqual(a, []);
-});
-
-test("evaluateAlerts: never throws on garbage input", () => {
-  assert.doesNotThrow(() => evaluateAlerts());
-  assert.doesNotThrow(() => evaluateAlerts(null));
-  assert.doesNotThrow(() => evaluateAlerts({ snapshot: 42, ledger: "x", presence: [] }));
-  assert.deepEqual(evaluateAlerts({ snapshot: 42, ledger: "x", presence: [] }), []);
-});
-
-// ---------------------------------------------------------------------------
-// emitAlerts — injected sink, never live
-// ---------------------------------------------------------------------------
-
-test("emitAlerts: posts every alert to the injected sink", async () => {
-  const posted = [];
-  const sink = (alert) => {
-    posted.push(alert);
-    return true;
-  };
-  const alerts = [
-    { id: "a", severity: "warning", detail: "x" },
-    { id: "b", severity: "critical", detail: "y" },
-  ];
-  const summary = await emitAlerts(alerts, { sink });
-  assert.equal(summary.attempted, 2);
-  assert.equal(summary.delivered, 2);
-  assert.equal(summary.failed, 0);
-  assert.deepEqual(posted.map((a) => a.id), ["a", "b"]);
-});
-
-test("emitAlerts: async sink is awaited; undefined return counts as delivered", async () => {
-  const seen = [];
-  const sink = async (alert) => {
-    await Promise.resolve();
-    seen.push(alert.id);
-    // returns undefined
-  };
-  const summary = await emitAlerts([{ id: "z", severity: "warning", detail: "d" }], { sink });
-  assert.equal(summary.delivered, 1);
-  assert.deepEqual(seen, ["z"]);
-});
-
-test("emitAlerts: a throwing sink fails that alert but not the rest", async () => {
-  const delivered = [];
-  const sink = (alert) => {
-    if (alert.id === "boom") throw new Error("sink down");
-    delivered.push(alert.id);
-    return true;
-  };
-  const summary = await emitAlerts(
-    [
-      { id: "ok1", severity: "warning", detail: "" },
-      { id: "boom", severity: "critical", detail: "" },
-      { id: "ok2", severity: "warning", detail: "" },
-    ],
-    { sink }
-  );
-  assert.equal(summary.attempted, 3);
-  assert.equal(summary.delivered, 2);
-  assert.equal(summary.failed, 1);
-  assert.deepEqual(delivered, ["ok1", "ok2"]);
-  assert.deepEqual(summary.results.find((r) => r.id === "boom"), { id: "boom", ok: false });
-});
-
-test("emitAlerts: a sink returning false is a failed delivery", async () => {
-  const summary = await emitAlerts([{ id: "a", severity: "warning", detail: "" }], {
-    sink: () => false,
-  });
-  assert.equal(summary.delivered, 0);
-  assert.equal(summary.failed, 1);
-});
-
-test("emitAlerts: no sink wired counts as failed (raised but went nowhere)", async () => {
-  const summary = await emitAlerts([{ id: "a", severity: "warning", detail: "" }], {});
-  assert.equal(summary.attempted, 1);
-  assert.equal(summary.delivered, 0);
-  assert.equal(summary.failed, 1);
-});
-
-test("emitAlerts: never throws on garbage", async () => {
-  await assert.doesNotReject(() => emitAlerts());
-  await assert.doesNotReject(() => emitAlerts(null, null));
-  const s = await emitAlerts("not-an-array", { sink: () => true });
-  assert.equal(s.attempted, 0);
-});
-
-// ---------------------------------------------------------------------------
-// thresholds config
-// ---------------------------------------------------------------------------
-
-test("loadThresholds: returns defaults when no config file present", async () => {
-  const t = await loadThresholds({ configPath: "/nonexistent/alerts.yaml" });
-  assert.equal(t.refusalSpike.warnCount, DEFAULT_THRESHOLDS.refusalSpike.warnCount);
-  assert.equal(t.daemonDown.critSec, DEFAULT_THRESHOLDS.daemonDown.critSec);
-});
-
-test("mergeThresholds: deep-merges override over defaults without mutating defaults", () => {
-  const merged = mergeThresholds(DEFAULT_THRESHOLDS, { refusalSpike: { warnCount: 1 } });
-  assert.equal(merged.refusalSpike.warnCount, 1);
-  // Sibling keys preserved.
-  assert.equal(merged.refusalSpike.critCount, DEFAULT_THRESHOLDS.refusalSpike.critCount);
-  // Defaults untouched (frozen + cloned).
-  assert.equal(DEFAULT_THRESHOLDS.refusalSpike.warnCount, 10);
-});
-
-// ---------------------------------------------------------------------------
-// internals
-// ---------------------------------------------------------------------------
-
-test("p99: nearest-rank, tolerant of junk, null on empty", () => {
-  assert.equal(_internals.p99([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]), 10);
-  assert.equal(_internals.p99([5]), 5);
-  assert.equal(_internals.p99([]), null);
-  assert.equal(_internals.p99("nope"), null);
-  assert.equal(_internals.p99([1, "x", 3, null, 2]), 3); // junk dropped → [1,2,3]
-});

package/lib/diagnostics/backup-freshness.test.mjs

@@ -1,185 +0,0 @@
-/**
- * backup-freshness.test.mjs — coverage for lib/diagnostics/backup-freshness.mjs.
- *
- * Hermetic: every case builds a tmp `.maestro/` fixture (config + marker) and
- * injects `now`, so no real backup machinery runs. Verifies the configured /
- * stale / ageHours verdict for the cases doctor + alerting depend on.
- */
-
-import { test } from "node:test";
-import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { backupFreshness, DEFAULT_STALE_HOURS } from "./backup-freshness.mjs";
-
-const HOUR = 3_600_000;
-
-/** Build a tmp agent root with optional backup-config.yaml + last-backup.json. */
-function makeAgent({ configBody, marker } = {}) {
-  const root = mkdtempSync(join(tmpdir(), "bf-test-"));
-  mkdirSync(join(root, ".maestro"), { recursive: true });
-  if (configBody !== undefined) {
-    writeFileSync(join(root, ".maestro", "backup-config.yaml"), configBody);
-  }
-  if (marker !== undefined) {
-    writeFileSync(
-      join(root, ".maestro", "last-backup.json"),
-      typeof marker === "string" ? marker : JSON.stringify(marker)
-    );
-  }
-  return root;
-}
-
-function cleanup(root) {
-  rmSync(root, { recursive: true, force: true });
-}
-
-test("unconfigured (no files) → configured:false, not stale, no age", () => {
-  const root = makeAgent();
-  try {
-    const r = backupFreshness({ agentRoot: root, now: Date.now() });
-    assert.equal(r.configured, false);
-    assert.equal(r.stale, false);
-    assert.equal(r.lastBackupAt, null);
-    assert.equal(r.ageHours, null);
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("scaffold default (enabled: false) → configured:false", () => {
-  const root = makeAgent({ configBody: "enabled: false\nprovider: gcs\n" });
-  try {
-    const r = backupFreshness({ agentRoot: root });
-    assert.equal(r.configured, false);
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("enabled: true with a fresh marker → configured, not stale, age computed", () => {
-  const now = Date.parse("2026-06-11T12:00:00Z");
-  const completed_at = new Date(now - 6 * HOUR).toISOString(); // 6h ago
-  const root = makeAgent({
-    configBody: "enabled: true\nprovider: gcs\nbucket: x\nprefix: y\n",
-    marker: { completed_at, provider: "gcs", size_bytes: 1234 },
-  });
-  try {
-    const r = backupFreshness({ agentRoot: root, now });
-    assert.equal(r.configured, true);
-    assert.equal(r.stale, false);
-    assert.equal(r.lastBackupAt, completed_at);
-    assert.equal(r.ageHours, 6);
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("enabled with a marker older than the window → stale", () => {
-  const now = Date.parse("2026-06-11T12:00:00Z");
-  const completed_at = new Date(now - 72 * HOUR).toISOString(); // 72h ago > 48h default
-  const root = makeAgent({
-    configBody: "enabled: true\n",
-    marker: { completed_at },
-  });
-  try {
-    const r = backupFreshness({ agentRoot: root, now });
-    assert.equal(r.configured, true);
-    assert.equal(r.ageHours, 72);
-    assert.equal(r.stale, true);
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("stale boundary: exactly at staleHours is fresh; just over is stale", () => {
-  const now = Date.parse("2026-06-11T12:00:00Z");
-  const atBoundary = new Date(now - DEFAULT_STALE_HOURS * HOUR).toISOString();
-  const overBoundary = new Date(now - (DEFAULT_STALE_HOURS * HOUR + 60_000)).toISOString();
-  const rootA = makeAgent({ configBody: "enabled: true\n", marker: { completed_at: atBoundary } });
-  const rootB = makeAgent({ configBody: "enabled: true\n", marker: { completed_at: overBoundary } });
-  try {
-    assert.equal(backupFreshness({ agentRoot: rootA, now }).stale, false, "exactly at window is fresh");
-    assert.equal(backupFreshness({ agentRoot: rootB, now }).stale, true, "just over window is stale");
-  } finally {
-    cleanup(rootA);
-    cleanup(rootB);
-  }
-});
-
-test("custom staleHours is honoured", () => {
-  const now = Date.parse("2026-06-11T12:00:00Z");
-  const completed_at = new Date(now - 10 * HOUR).toISOString();
-  const root = makeAgent({ configBody: "enabled: true\n", marker: { completed_at } });
-  try {
-    // 10h old: stale under an 8h window, fresh under the 48h default.
-    assert.equal(backupFreshness({ agentRoot: root, now, staleHours: 8 }).stale, true);
-    assert.equal(backupFreshness({ agentRoot: root, now }).stale, false);
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("configured but NO marker → stale (a backup that never ran)", () => {
-  const root = makeAgent({ configBody: "enabled: true\n" });
-  try {
-    const r = backupFreshness({ agentRoot: root, now: Date.now() });
-    assert.equal(r.configured, true);
-    assert.equal(r.lastBackupAt, null);
-    assert.equal(r.ageHours, null);
-    assert.equal(r.stale, true);
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("configured with a corrupt marker → stale, not a throw", () => {
-  const root = makeAgent({ configBody: "enabled: true\n", marker: "{not json" });
-  try {
-    const r = backupFreshness({ agentRoot: root, now: Date.now() });
-    assert.equal(r.configured, true);
-    assert.equal(r.lastBackupAt, null);
-    assert.equal(r.stale, true);
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("future-dated marker (clock skew) is treated as fresh, not stale", () => {
-  const now = Date.parse("2026-06-11T12:00:00Z");
-  const completed_at = new Date(now + 2 * HOUR).toISOString(); // 2h in the future
-  const root = makeAgent({ configBody: "enabled: true\n", marker: { completed_at } });
-  try {
-    const r = backupFreshness({ agentRoot: root, now });
-    assert.equal(r.stale, false);
-    assert.ok(r.ageHours < 0, "negative age for a future marker");
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("explicit configPath + markerPath overrides agentRoot", () => {
-  const now = Date.parse("2026-06-11T12:00:00Z");
-  const root = mkdtempSync(join(tmpdir(), "bf-explicit-"));
-  const cfg = join(root, "cfg.yaml");
-  const mk = join(root, "marker.json");
-  writeFileSync(cfg, "enabled: true\n");
-  writeFileSync(mk, JSON.stringify({ completed_at: new Date(now - HOUR).toISOString() }));
-  try {
-    const r = backupFreshness({ configPath: cfg, markerPath: mk, now });
-    assert.equal(r.configured, true);
-    assert.equal(r.ageHours, 1);
-    assert.equal(r.stale, false);
-  } finally {
-    cleanup(root);
-  }
-});
-
-test("never throws on a totally bogus cfg", () => {
-  assert.doesNotThrow(() => backupFreshness(null));
-  assert.doesNotThrow(() => backupFreshness({ agentRoot: 42, now: "x" }));
-  const r = backupFreshness({ configPath: 12345 });
-  assert.equal(typeof r.configured, "boolean");
-});