ADR-0198accepted

Adaptive Heartbeat — Check Cheaply, Act Rarely

Status

Accepted

Context

joelclaw’s heartbeat functions run on cron and do work every invocation — health checks, gateway pings, memory operations. Most of the time, nothing has changed and the work is wasted cycles/tokens.

Utah’s heartbeat runs every 30 minutes but gates on two cheap checks before firing the expensive LLM distillation:

  1. Daily log size > 4KB threshold
  2. Hours since last distill > 8h max

Most runs are just a file stat + string parse — zero LLM cost. Only when logs have accumulated enough content does it actually call the model.

Decision

Adopt the “check cheaply, act rarely” pattern for all periodic joelclaw functions:

  1. Every cron function gets a cheap gate step — first step checks if work is needed using file stats, Redis reads, or simple comparisons. No LLM, no heavy I/O.
  2. Early return with reason — if gate fails, return { status: "skipped", reason: "..." } immediately
  3. Structured thresholds — each function defines its trigger thresholds (size, time, count) as config, not hardcoded
  4. Apply to existing functions:
    • check-gateway-health — skip if last check was <10min ago and no error events
    • memory-observe — skip if no new session content since last observation
    • adr-daily-pitch — already has date-based gating, add pitch history check
    • Feed check functions — skip if last check was recent and no new items

Consequences

  • Reduced cost — fewer unnecessary LLM calls and API hits
  • Better observability — Inngest dashboard shows skip/act ratio per function
  • Slight complexity — each function needs gate logic, but it’s a simple pattern
  • Risk — aggressive gating could delay time-sensitive actions; thresholds need tuning

Agent Readiness

  • Confidence: 5 — trivial pattern, Utah proves it works
  • Agent-ready: 5 — mechanical refactor of existing functions
  • NRC: Low — add a gate step to existing functions
  • Novelty: Low — standard optimization pattern

References