hermes - 💡(How to fix) Fix [Feature]: First-class agent heartbeat jobs for supervised long-running projects [1 comments, 1 participants]

Feature Description

Add a first-class agent heartbeat primitive to Hermes: a recurring scheduled wake-up that starts a fresh agent run with configured context, skills, toolsets, state checks, and guardrails.

This is different from current cron reminders and different from "still running..." progress pings.

A heartbeat should mean:

At every interval, Hermes wakes the agent, gives it the project context and tools, lets it inspect current state, decide whether a safe micro-action is needed, execute that bounded action, and report back.

Motivation

For supervised long-running projects, users often do not want a blind autonomous cron job that repeatedly executes the same worker script. They want an agent to periodically re-evaluate the world and make conservative decisions.

Real example: academic paper collection / Paperika.

• Blind downloader cron can pile up failures, hit rate limits, or continue after authentication breaks.
• A mere reminder cron only sends messages like "remember to continue" but does not actually wake the agent with tools.
• The desired behavior is a heartbeat that wakes Luna/Hermes, checks state files, checks Chrome/CDP readiness, detects blockers/rate limits, optionally does one tiny verified batch, and reports exactly what changed.

The user's correction was essentially:

A heartbeat is the one where you get prompted anytime the heartbeat runs, right?

Meaning: it should wake the agent to act, not just notify the human.

Proposed Solution

Add a dedicated heartbeat abstraction on top of / alongside cron jobs.

Desired UX

CLI examples:

hermes heartbeat create \
  --name paperika-jocn \
  --schedule "every 90m" \
  --skills paperika-downloader \
  --toolsets terminal,file \
  --deliver origin \
  --prompt-file paperika-heartbeat.md

hermes heartbeat list
hermes heartbeat pause paperika-jocn
hermes heartbeat run paperika-jocn

Gateway/slash examples:

/heartbeat create every 90m: check Paperika state, do at most one safe verified micro-batch, report back
/heartbeat list
/heartbeat pause paperika-jocn

Semantics

A heartbeat run should:

1. Start a fresh agent invocation, not just send a static reminder.
2. Load configured skills and selected toolsets.
3. Receive self-contained project context plus previous heartbeat summary/state if available.
4. Have an explicit bounded-action contract:
   • inspect state
   • detect blockers
   • avoid duplicate workers
   • optionally perform a small safe action
   • verify outcome
   • report before/after state
5. Persist heartbeat-specific run metadata:
   • last run time
   • last action taken
   • last status
   • consecutive failures
   • next recommended action
6. Support user-visible delivery back to the originating chat/topic.
7. Be distinguishable from normal cron reminders in UI/listing.

Difference from Existing Issues

Related but distinct:

• #9116 and #14425: long-running tool/status heartbeat — "Hermes is still working."
• This issue: scheduled agent heartbeat — "Hermes wakes up periodically to inspect, decide, and possibly act."

Both are useful, but they solve different failure modes.

Example Heartbeat Prompt Contract

You are the Paperika heartbeat agent.

Every run:
1. Read download_state.json and manifest_enriched.json.
2. Run `python -m paperika doctor`.
3. If Chrome/CDP is down, start local Chrome and verify CDP.
4. If another worker is already running, do not start another.
5. If rate-limited or auth-blocked, stop and report blocker.
6. If safe, process at most 1-2 pending papers.
7. Verify PDFs before marking success.
8. Report before counts, actions, after counts, and next step.

Why not just cron?

Cron can already run prompts, but the current UX makes it too easy to create one of two wrong things:

1. Reminder-only cron: sends text but cannot act because toolsets/skills/context are missing.
2. Blind automation cron: repeats a worker script without agent-level inspection or adaptation.

A first-class heartbeat should encode the intended middle ground: recurring, agent-led, bounded, state-aware supervision.

Acceptance Criteria

• Users can create/list/pause/resume/run heartbeat jobs separately from generic cron reminders.
• Heartbeat jobs support skills, toolsets, delivery target, schedule, and self-contained context.
• Heartbeat runs include a standard summary schema: inspected state, action taken, verification, blocker, next step.
• UI/CLI makes it clear whether a scheduled job is reminder-only, blind command/worker, or agent heartbeat.
• Docs include examples for long-running research/data-collection projects.
• Gateway delivery works in Telegram topics/threads via origin delivery.

Alternatives Considered

• Use existing cron directly: technically possible but confusing; this exact confusion caused a heartbeat to be configured as message-only.
• Keep blind cron worker: risky for rate-limited/authenticated workflows.
• Human-only reminders: too passive; does not reduce user management burden.

Priority

P2/P3. Not a crash bug, but it is a major usability primitive for Hermes as a long-running personal agent rather than just a chat interface.