@alef/omnisentinel

Portable runtime observability + graceful degradation for any Node.js process.

Decoupled from ALEF core. Drop into any Node/Python service. Same architectural benefits without the framework lock-in.

Why

Most services have one of two visible states: "running" or "dead". You discover dead-state through alerts AFTER the failure already hurt the user. OmniSentinel adds a middle layer:

• Per-agent sidecar heartbeats — append-only JSONL, the SOLE evidence when a process crashes
• Fleet-level monitor — classifies each agent as FRESH/WARM/STALE/DEAD/GHOST/STOPPED
• Survival mode — when resources or upstream degrade, automatically reduce load instead of crashing

The contract is JSON-Lines per agent + a single status file. Python and other languages can write to the same JSONL files via the documented schema.

Install

npm install @alef/omnisentinel

Use — single-agent heartbeat

import { sentinel } from "@alef/omnisentinel";

const s = sentinel({ name: "my-service", dir: "./meta/sentinel" });
s.boot("v1.0.0 starting");
s.heartbeat("processing payment", { state: "active", confidence_score: 0.95 });
s.startTimer(60_000);  // periodic heartbeat
process.on("SIGINT", () => { s.shutdown("SIGINT"); process.exit(0); });

Use — fleet monitor

import { runMonitor } from "@alef/omnisentinel/monitor";

runMonitor({
  dir: "./meta/sentinel",
  statusFile: "./meta/sentinel_status.json",
  tickSec: 30,
  knownAgents: ["api-server", "worker-1"],
});

Use — survival mode

import { runSurvival } from "@alef/omnisentinel/survival";

runSurvival({
  flagFile: "./automation/SURVIVAL_MODE_ACTIVE",
  memMinMb: 200,
  upstreamHealthFn: (sig) => checkLLM() ? 0 : 1.0,
});

Loops read the flag at top of iteration:

if (existsSync("./automation/SURVIVAL_MODE_ACTIVE")) {
  await sleep(cooldownMs * 10);
  continue;
}

License

CC-BY-4.0. See Doctrine #32 — The Sentinel Rule for architectural rationale.