@cohortapp/agent-sdk 2.8.0 → 2.8.1

package/lib/telemetry/collect.mjs

@@ -241,6 +241,47 @@ function humanActivity(intent, taskClass) {
  *   uptimeDays?:number, spend24h?:number, device?:string, ram?:string, cores?:number
  * }>}
  */
+/**
+ * Percentage of memory genuinely unavailable.
+ *
+ * On macOS this is `100 - (memory_pressure's System-wide memory free
+ * percentage)`. That is the same source `scripts/watchdog/memory-watchdog.sh`
+ * thresholds on, so the number in the Fleet view and the number the watchdog
+ * acts on can no longer disagree — they used to disagree by ~66 points, which
+ * is how a healthy machine came to show a standing CRITICAL.
+ *
+ * Anywhere else (or if memory_pressure yields nothing) falls back to
+ * `1 - free/total`, which on Linux does mean what it says.
+ *
+ * @param {object} o    collector options; `o.execFile` is the test seam
+ * @param {object} osImpl
+ * @returns {Promise<number>}
+ */
+async function collectMemUsedPct(o, osImpl) {
+  const fallback = () => {
+    try {
+      const total = Number(osImpl.totalmem());
+      const free = Number(osImpl.freemem());
+      if (Number.isFinite(total) && total > 0 && Number.isFinite(free)) {
+        return pct((1 - free / total) * 100);
+      }
+    } catch { /* fall through */ }
+    return 0;
+  };
+
+  const platform = o.platform || process.platform;
+  if (platform !== "darwin" && !o.execFile) return fallback();
+
+  const execFileImpl = o.execFile || execFile;
+  const out = await execFileSafe(execFileImpl, "/usr/bin/memory_pressure", [], 4000);
+  const m = /System-wide memory free percentage:\s*([\d.]+)%/.exec(out || "");
+  if (!m) return fallback();
+
+  const freePct = Number(m[1]);
+  if (!Number.isFinite(freePct) || freePct < 0 || freePct > 100) return fallback();
+  return pct(100 - freePct);
+}
+
 export async function collectMachine(o = {}) {
   const osImpl = o.os || os;
   const machine = { loadavg: [0, 0, 0], memUsedPct: 0 };
@@ -253,14 +294,21 @@ export async function collectMachine(o = {}) {
     }
   } catch { /* keep [0,0,0] */ }
 
-  // memUsedPct = 1 - free/total
-  try {
-    const total = Number(osImpl.totalmem());
-    const free = Number(osImpl.freemem());
-    if (Number.isFinite(total) && total > 0 && Number.isFinite(free)) {
-      machine.memUsedPct = pct((1 - free / total) * 100);
-    }
-  } catch { /* keep 0 */ }
+  // memUsedPct — how much memory is genuinely UNAVAILABLE, not how much is
+  // merely occupied.
+  //
+  // This used to be `1 - os.freemem()/os.totalmem()`, which is not a pressure
+  // measure on macOS. os.freemem() counts only entirely-free pages, and macOS
+  // deliberately keeps almost all RAM occupied with file cache, purgeable and
+  // compressed pages that are reclaimable on demand. Measured on a healthy
+  // idle Mac mini M4 Pro at the same instant: os.freemem() → 99.2% "used",
+  // `memory_pressure` → 68% free. The old number sat permanently near 100 and
+  // fired CRITICAL alerts on machines with nothing wrong with them, while the
+  // memory watchdog — which reads memory_pressure — correctly stayed quiet.
+  //
+  // Prefer macOS's own answer; fall back to the free/total ratio only where
+  // memory_pressure does not exist (Linux, where the figure means what it says).
+  machine.memUsedPct = await collectMemUsedPct(o, osImpl);
 
   // cpuPct — coarse instantaneous estimate from loadavg/cpus when powermetrics
   // is unavailable. powermetrics (if it yields) overrides below.

package/lib/telemetry/collect.test.mjs

@@ -173,7 +173,11 @@ test("detectClaudeAuth: scans recent log files under agentRoot", () => {
 });
 
 test("collectMachine: derives memUsedPct + loadavg without powermetrics/df", async () => {
-  const m = await collectMachine({ os: fakeOs({ totalmem: 10e9, freemem: 2e9, loadavg: [4, 2, 1], cpus: 4 }), powermetrics: false, disk: false });
+  // memUsedPct now prefers macOS's memory_pressure, so "no external tools" has
+  // to include that one too — otherwise this test reads the REAL machine and
+  // asserts against the fake os, which is how it started failing.
+  const noTools = (cmd, args, opts, cb) => { cb(new Error("ENOENT")); return { on() {} }; };
+  const m = await collectMachine({ os: fakeOs({ totalmem: 10e9, freemem: 2e9, loadavg: [4, 2, 1], cpus: 4 }), execFile: noTools, powermetrics: false, disk: false });
   assert.equal(m.memUsedPct, 80);
   assert.deepEqual(m.loadavg, [4, 2, 1]);
   assert.equal(m.cpuPct, 100); // load 4 / 4 cpus = 100%
@@ -662,3 +666,75 @@ test("collectStatus ships the FULL machine vocabulary the Fleet row reads", asyn
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// memUsedPct — pressure, not occupancy
+//
+// This was `1 - os.freemem()/os.totalmem()`, which is not a pressure measure on
+// macOS: os.freemem() counts only entirely-free pages, and macOS keeps nearly
+// all RAM occupied with file cache, purgeable and compressed pages that are
+// reclaimable on demand. Measured on a healthy idle Mac mini M4 Pro at one
+// instant: os.freemem() → 99.2% "used", memory_pressure → 68% free. The seat
+// showed a standing CRITICAL while the watchdog, reading memory_pressure,
+// correctly did nothing.
+// ---------------------------------------------------------------------------
+
+test("memUsedPct comes from memory_pressure, not from free/total", async () => {
+  const seen = [];
+  const execFile = (cmd, args, opts, cb) => {
+    seen.push(cmd);
+    if (cmd === "/usr/bin/memory_pressure") {
+      cb(null, "System-wide memory free percentage: 68%\n");
+    } else {
+      cb(new Error("not stubbed"));
+    }
+    return { on() {} };
+  };
+  // An os whose free/total ratio would say 99% used — the old, wrong answer.
+  const osImpl = {
+    loadavg: () => [1, 1, 1],
+    totalmem: () => 24 * 1024 ** 3,
+    freemem: () => 0.2 * 1024 ** 3,
+    cpus: () => [],
+    uptime: () => 3600,
+  };
+
+  const m = await collectMachine({ execFile, os: osImpl, platform: "darwin" });
+
+  assert.equal(m.memUsedPct, 32, "100 - 68 free, i.e. what the watchdog thresholds on");
+  assert.notEqual(m.memUsedPct, 99, "the free/total ratio must not be the answer on darwin");
+  assert.ok(seen.includes("/usr/bin/memory_pressure"), "memory_pressure is consulted");
+});
+
+test("memUsedPct falls back to free/total when memory_pressure yields nothing", async () => {
+  // Linux, or a macOS where the binary is missing/erroring. There the ratio
+  // does mean what it says, so a fallback is right — silence is not.
+  const execFile = (cmd, args, opts, cb) => { cb(new Error("ENOENT")); return { on() {} }; };
+  const osImpl = {
+    loadavg: () => [0, 0, 0],
+    totalmem: () => 1000,
+    freemem: () => 250,
+    cpus: () => [],
+    uptime: () => 1,
+  };
+
+  const m = await collectMachine({ execFile, os: osImpl, platform: "darwin" });
+  assert.equal(m.memUsedPct, 75, "1 - 250/1000");
+});
+
+test("memUsedPct ignores an out-of-range memory_pressure reading", async () => {
+  const execFile = (cmd, args, opts, cb) => {
+    cb(null, "System-wide memory free percentage: 8000%\n");
+    return { on() {} };
+  };
+  const osImpl = {
+    loadavg: () => [0, 0, 0],
+    totalmem: () => 1000,
+    freemem: () => 400,
+    cpus: () => [],
+    uptime: () => 1,
+  };
+
+  const m = await collectMachine({ execFile, os: osImpl, platform: "darwin" });
+  assert.equal(m.memUsedPct, 60, "a nonsense percentage falls back rather than propagating");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "Cohort Agent SDK \u2014 autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {