Diagnostics Endpoints (new in v2.0.45+)

Two superadmin endpoints for live operational triage. Both require a valid superadmin session JWT (the user-session token from POST /agenthub/api/auth/login, not a tenant API key).

Endpoint	Method	Purpose
/admin/diagnostics/memory	GET	Returns process.memoryUsage() + uptime + PID. Cheap, pollable. Use to watch how RSS diverges from the JS heap — when rss >> heapUsed (e.g., 2.8 GB RSS vs 170 MB heap), the leak is native (LanceDB, bun:sqlite, Bun allocator), not in the JS heap.
/admin/diagnostics/heap-snapshot	POST	Writes a V8 heap snapshot to $DATA_DIR/heap-<ISO timestamp>.heapsnapshot. Pull out via docker cp and open in Chrome DevTools → Memory tab. Use the “Compare” view between two snapshots taken minutes apart to identify the dominant retained-size delta. Snapshots only contain JS heap; consult memory first to confirm the leak is JS-side.

Example workflow when investigating an OOM:

TOKEN=$(curl -s -X POST https://<host>/agenthub/api/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"superadmin@example.com","password":"…"}' | jq -r .token)

# Cheap pulse
curl -s -H "Authorization: Bearer $TOKEN" \
  https://<host>/agenthub/admin/diagnostics/memory | jq

# Capture snapshots and compare
curl -s -X POST -H "Authorization: Bearer $TOKEN" \
  https://<host>/agenthub/admin/diagnostics/heap-snapshot | jq

Sample output of /admin/diagnostics/memory:

{
  "rss": 2891841536,
  "heapTotal": 133950464,
  "heapUsed": 170446061,
  "external": 25957834,
  "arrayBuffers": 2699300,
  "uptimeSec": 602,
  "pid": 172,
  "sampledAt": "2026-05-28T18:12:22.791Z"
}

Here rss / heapUsed ≈ 17× → the leak is in native memory, not JS. Reach for a heap snapshot only when that ratio is much smaller.

---